Manage custom objects
This article covers managing records for a custom object.
POST
Create custom object records
This example custom object has 3 attributes defined:
attributeOne: single-value string
attributeTwo: single-value string
resolve: an object that specifies how relationships are resolved; see more info below.
Note:
The body is a regular JSON format, so numbers, string, and arrays are formatted per JSON format.
Dates are timestamp RFC3339 format.
All the custom objects defined for you will have an
id
property marked as unique which can be used as a lookup key during upsert operationsThe syntax for
resolve
is:Destination_property_key
It’s an array of resolve objects; This is currently not fully supported so you need to use only 1 element in this array.
The
resolve
path object is having 2 propertiesPath: json path to a unique field on the related object; example:
bird.identifiers.useruuid
: this will find contact objects searching on useruuid identifier.id
: this will find other custom object searching against their id attribute
Value: value to search for eg useruuid
If you resolve an attribute, then the attribute’s value cannot be provided in the object payload also.
curl --location 'https://api.bird.com/workspaces/{workspaceId}/catalog/objects/{custom_object_type_key} \
--header 'Content-Type: application/json' \
--data '{
"body": {
"attributeOne": "{some_value}",
"attributeTwo": "{some_value}"
},
"resolve": {
"{attribute_on_custom_object_type}": [
{
"path": "{path_to_unique_attribute_on_the_related_entitty}",
"value": "{value_to_search_for}"
}
]
}
}'
Bulk Operation to Create, Update, Upsert and Delete
When upserting large quantities of objects, you should use Bulk Write API, which provides access to all CRUD operations, but allows you to submit up to 1000 object records in a single API request, though we recommend using 200 records.
When executing bulk operations, an operation
type has to be provided:
create - creates specified objects. ID should not be specified. It fails if a unique value is already used by another object.
update - updates specified objects. ID should be specified. It fails if the object is not found.
upsert - updates or creates objects. If ID is not specified, it uses unique values specified in the body to look up an existing object.
delete - deletes specified objects. If ID is not specified, it uses unique values specified in the body to look up an existing object.
curl --location 'https://api.bird.com/workspaces/{workspace_id}/catalog/objects/billing_contracts/bulk-write' \
--data '{
"operation": "upsert",
"duplicateBehavior": "lastWins",
"items": [
{
"body": {
"id": "7758281",
"createdAt": "2024-10-29T10:26:43.083Z",
"updatedAt": "2024-10-29T10:26:43.083Z",
"contractDateStart": "2024-10-29",
"contractVersion": 1,
"status": "ACTIVE",
"subStatus": "NONE",
"subscriptionType": "PERSON_PREMIUM_V1"
},
"resolve": {
"userId": [
{
"path": "bird.identifiers.userid",
"value": "1630605"
}
]
}
}
]
}'
The response (200) of bulk write operation may contain errors related to each supplied object record. It may partially succeed, and you will receive a response which specifies which input items resulted in a created object and which ones errored:
{
"objects": {
"0": {
"type": "{custom-object-type-key}",
"id": "376cc7cc-862b-4155-8bec-6251dc1583f5",
"body": {
"birthday": "1992-05-05",
"contactId": "c9e25235-2970-490d-a8f0-b697995d1dc4",
"gender": "F",
"phoneNumber": "+31620984111"
},
"refs": [
{
"type": "bird.contact",
"path": "contactId",
"ids": [
"c9e25235-2970-490d-a8f0-b697995d1dc4"
]
}
],
"uniques": [
{
"path": "number",
"value": "654321"
}
],
"createdAt": "2024-09-04T20:00:36.767Z",
"updatedAt": "2024-09-04T20:02:15.924Z"
}
},
"errors": {
"1": {
"resolve.contactId": [
"failed to resolve reference"
]
}
}
}
Search Custom object records
This POST call will get the results for custom object records which match the the value of a custom object attribute such as an externalID.
POST
https://app.bird.com/api/workspaces/875c83df-62b5-49c7-b9ca-fda947b2cac2/catalog/objects/{{custom_object_name}}/search?limit=40
{"query":{"operator":"and","children":[{operator: "string/equals", attributeName: "externalID", value: "valueoftheexternalid"}]},"sortBy":"updatedAt","sortOrder":"desc"}
Update custom object records
PATCH
This PATCH request specifies that we want to change the value of attributeOne of the object identified by custom_object_id
:
attributeOne: single-value string
Note: this is a patch request, so only the specified attributes are going to be updated, the attributes not specified in the request will be left untouched.
curl --location 'https://api.bird.com/workspaces/{workspaceId}/catalog/objects/{custom_object_type_key}/{custom_object_id} \
--header 'Accept: application/json, text/plain, */*' \
--header 'Content-Type: application/json' \
--data '{
"body": {
"attributeOne": "{some_value}"
}
}'
Last updated
Was this helpful?