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 operations
The 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 properties
  - Path: 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 22 days ago

Was this helpful?