SKY Developer API returning invalid gift_id

Kevin Hathorn

We have a “Developer” account for the “sandbox" (Developer Cohort test environment) environment that we use for testing our Raiser'sEdge integration. The gift API is supposed to return id(s) of the gift(s) after a successful POST request. This works in the API Explorer, but when we actually post from the app, the id's returned are not valid. We are capturing the id and using to send follow-up requests (custom_fields) but receive “resource not found” error. This makes our implementation IMPOSSIBLE to test. I have successfully completed the same flow using the API explorer. Please fix. There's a host of other issues with the developer account limitations and inconsistencies with the “production” environment that make it very difficult to test and predict outcomes, but they need to be addressed separately, not here.

Kevin Hathorn

FYI the constituent and gift_batch endpoints use the same response behavior and actually DO return valid id's that can be used to perform follow-up posts to the constituent/batches. So the gift api, with the same stated response behavior, is out of sync.

Kevin Hathorn

It now appears, after two years of no action or responses on this issue, the gift batch api is now behaving the same way. This makes it absolutely impossible to test any follow-up requests that use the giftid (custom field relays, etc). Sure would be nice to get some help here.

Alex Wong

@Kevin Hathorn
If you suspect the API has bug and return wrong information, you can report it via support, and here in community. I'm surprise no one responded to you, but maybe community was different in 2021 without proper staffing. I'm glad you bring this up again with a new post.

I have not specifically used the POST endpoint to create a new gift record with Gift v1, however, I am using Gift v2 POST to create new Pledge record and the returned gift id is correct and I use it to add gift custom fields and add file attachment to the new pledge.

And you said that using the console provides the correct gift id back, so it should mean that the endpoint is working properly. Can you provide more info on how you are using the POST api? You are stating that the API returned invalid gift id, did you on RE NXT if the gift id point to anything?

I will give this a try and let you know, but if you can provide more info, will help me help you

Alex Wong

@Kevin Hathorn
I just tried this and is working correctly.

returned the gift id of the created gift

using the gift id returned, create a gift custom field

In RE NXT, the new gift is shown with the gift system id returned, and the gift has the gift custom field created by the program

So since the endpoint is working properly, now the question is how you are using the endpoint and if your code is getting the info correctly. Please share what you have so we can diagnose further.

Kevin Hathorn

@Alex Wong
This is the exact response from BB gifts(batch) api endpoint:
"gifts": [{
"id": "7678",
…
}]
That there is supposed to be the internal_id of the gift, which can be used to make further calls on the gifts api. We are doing the exact same thing with the Constituent API without issue (make a call to find or create constituent, then use the returned constituent ID to make subsequent calls). Same flow, but in the sandbox env, the API always returns gift ids that get “resource not found" response.
The ACTUAL internal gift id for the above referenced gift is 288318, which I had to find by using the UI and finding the gift that was created via the API. I verified that 288318 is the internal ID.

To be clear, this is only happening (I think) in sandbox. The production environment seems to be returning valid gift_id here.
The problem is, when we need to do some iterating, we cannot test the feature, we just have to deploy to prod and cross our fingers. That's not good.

Kevin Hathorn

@Alex Wong
as mentioned in the other reply, this seems to be endpoint specific, so Pledge endpoint may be fine. I've not found this bad behavior on other endpoints.

Alex Wong

@Kevin Hathorn
My attempt was using these 2 endpoints, can you link which endpoint is failing for you.

Kevin Hathorn

@Alex Wong

Alex Wong

@Kevin Hathorn
You are using the add gift to batch endpoint, so when the POST call is completed, the gifts are added to the gift batch with ID being returned, however, the gift batch has YET to commit (I don't think there is a commit gift batch endpoint, let me know if there is one). Since I never use gift batches for automation of gift entry, I don't have much details here and testing it out may need me to commit a batch so I won't be doing it (others may be able to comment).

However, giving my 2 cents here on “potential logic” here on the endpoints.

Since the gift are in gift batch and the gift batch is not yet committed, while the gift ID is likely valid gift ID, you are unlikely able to invoke other gift endpoint (i.e. create gift custom field) on the uncommitted gift. I don't really think it has to do with sandbox or production here. Try “breaking” your app in 2, or create a “pause and wait" in your app after the gifts has been added to the gift batch, then manually go commit the gift batch in RE NXT. Then signal your app to continue, if the subsequent endpoint call to add to the gifts is successful, then it just means these subsequent endpoint call only works on committed gift, not gift in gift batches.

As for your comment that the batching works with constituent API, I do not think there is a “similiar” process/endpoint for constituent here. There is no “add constituent to constituent batch” (not that I know of / able to find). Meaning when you create constituent directly, the constituent is already “exist” and created in RE NXT, so any subsequent call to add to the constituent (i.e. constituent custom field) would be successful since the record is a “real” record.

Kevin Hathorn

@Alex Wong
Thing is, everything works fine in production. I just verified via actual request records once again that a valid gift_id is returned from the API when adding a gift via the add gift to batch endpoint. This is absolutely a sandbox bug.

Alex Wong

@Kevin Hathorn
Can you tell me which endpoint you were using AFTER adding the gift to the gift batch?

Also, when you say “Sandbox”, are you simply talking about another “environment” of RE NXT you are in? or a totally different configuration? (for example, we have 2 environments of RE NXT, one call “test envirionment” and one call “production environment” which are both accessible through the “pancake/database” icon:

Kevin Hathorn

@Alex Wong

I'm using the term “sandbox” generically here, the environment the developer account is linked to. I would guess the “test” environment. It's a public database, in the sense that all devs have access to the same records (I see donations/contacts being posted by other people from other orgs/companies).

The endpoint we are hitting, after receiving the gift_id, is the gift custom field collection endpoint.

Kevin Hathorn

@Alex Wong
You obviously are not on a “developer account”. You probably are not aware, Bb does not provide all the available features for developers, the dev accounts are severely and frustratingly limited, in fact. No database view. I think the db name is actually SKY Developer Cohort, but that's a guess from looking at the ui

Alex Wong

@Kevin Hathorn
If you are only hitting the create custom fields endpoint, any reason why you don't include the custom fields needed to be created directly from the request body of the POST to add gift to gift batch API call? The endpoint allows gift custom fields to be included as an array of custom_fields data.

As for the sandbox bug, I still don't quite understand your configuration, your developer account setup, etc. Without going too deep into asking you for more sensitive information, I think you are best to open a support ticket asking to report this bug and let the support team get you an internal resource to look into it. (it is hard to get pass first level support to the engineering team, but if you persist, you will get to one).

Alex Wong

@Kevin Hathorn
As mentioned on my latest post, we are probably talking apple to orange here. So I will stop digging deeper into the bug you are talking about, go to support.blackbaud.com and submit a ticket.

I do have a “developer” account, however, this “developer” account and “sandbox” you are referring to is likely not the same as what I have in mind. For clarity, I have an account on developer.blackbaud.com and have both my test amd production RE NXT instance connected. When I need to test any code, I connect my application to the test environment. The test envrionment is a “true” copy of our production environment config/data from ~1 year ago. So I do not know about this Cohort/sandbox that maybe Blackbaud provides.

Kevin Hathorn

@Alex Wong
Not all of our users that use Bb have their accounts configured for the custom fields. It's been a bit, but I think I recall that if they do not, the request will fail, and we do not want that to happen. Hence we do the custom field call separately. Perhaps something has changed and the API will accept the call and return errors for the custom fields, i'd have to test that out to determine.
Like I said, it works in production as is. Our internals are the same for both prod and test, and as far as Bb gives us the ability, our Bb instance is configured the same as our users have in production. That said, there's no configuration that should change whether or not Bb responds with valid id's. That would just be horrible architecture.

Alex Wong

@Kevin Hathorn
First, if it wasn't clear, I do not work for Blackbaud, been using API for 2 years now and really hasn't seen the discrepancy on other endpoints like you are claiming. That's why I find it odd.

Either way, since your post, which is 2 years already, API definitely has seen changes, so I wouldn't be surprise that when you were doing it, the add gift to gift batch API did not allow custom fields array to be included in request body, but now it does.

As for if there is different version of API in your prod vs sandbox, I'll have to refer you to someone from Blackbaud, open a support ticket is a starter.

@Ben Wong is a Blackbaud API engineer (sorry if I get your title/job wrong), which occasionally stroll into Community, so maybe he can shed some light.

Kevin Hathorn

@Alex Wong
I gathered that you did not work for Bb ?
Our organization does not use Bb ourselves, we have customers who do, so we use the API to sync data for them. We don't have any need to keep any data on Bb ourselves, so we do not have a production account, and I'm sure the access is different, even as a developer, when you do. I did confirm after looking around a bit more the Cohort db that is accessible for folks like me, and yeah it's not the same as your setup.
That's one of my complaints about the dev access, it's so different from what's available and used by Bb users with full access. It makes it extremely difficult to advise them and troubleshoot (as you've noted, it makes it extremely difficult for you to advise me!). The only reason I knew anything about how the db view looks and can be used is because we worked with a Bb poweruser (one of our customers) who knew all the ins and outs. He's no longer available. There are plenty of other features that do not exist via the API that are possible/available via other access, but I understand making Kevin's life easier is not their priority lol.

Appreciate you tagging Ben, I've worked with him a bit before and couldn't remember if it was with Bb or elsewhere.

Kevin Hathorn

Solved. After a whole lotta running around because the documentation is unclear, it turns out you have to hit the “Add Gift Custom Field Category” endpoint to get or create each custom field category, which returns the ID of the category. It is the ID, not the category name, that has to be used when adding custom fields on the gift (batch) body {category: id, value: “foo”}. This is an inconsistency because if you add the custom field via the gift custom field collection endpoint, you can use the “name” for the “category” (ie: { category: name, value: “foo” }. Many users have had the same difficulty in using these endpoints.

@Alex Wong you were correct that the ids being returned from the gift batch endpoint are not gift_ids (even though they are called that on multiple levels) but rather some kind of “import” id. The naming is unclear and should be fixed, but I doubt that will happen at this point.
It “appeared” that it was working in prod because BB (in rather poor form) is apparently still stuck on integer ids for all tables (rather than use the industry standard UUID, there's a reason for this). So the gift_id (gift import table? pending gifts table?) returned from the batch endpoint actually can match a completely unrelated gift_id in the (approved) gifts table. So records get erroneously added to that gifts table in those cases. No good.

Appreciate the time and attention you spent looking into this.