Get the records associated with an object record

GET

https://api.brevo.com/v3/objects/:object_type/associated-records

GET

/v3/objects/:object_type/associated-records

import { BrevoClient } from "@getbrevo/brevo";
async function main() {
    const client = new BrevoClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.customObjects.getAssociatedRecords({
        objectType: "vehicle",
        type: [
            "contact",
            "garage",
        ],
    });
}
main();

{
  "has_more": true,
  "items": [
    {
      "object": {
        "attributes": {
          "city": "Paris",
          "name": "Downtown Motors"
        },
        "created_at": "2026-07-22T10:20:30Z",
        "ext_id": "f7e8d9c0ba",
        "id": 12345,
        "updated_at": "2026-07-22T10:20:30Z"
      },
      "type": "garage"
    },
    {
      "object": {
        "attributes": {
          "email": "jane.doe@example.com",
          "ext_id": "crm-4471",
          "first_name": "Jane",
          "last_name": "Doe"
        },
        "id": 402
      },
      "type": "contact"
    }
  ],
  "offset": 0
}

Enterprise access only

Custom objects are only available to Enterprise plans. This feature is in beta. These are subject to change.

Returns the records associated with a single source record. Associations of every type are returned together in one paginated list, ordered by association creation time with the most recently created association first.

Identifying the source record Provide exactly one of id, ext_id, email or sms. Passing none of them, or more than one, returns 400. email and sms are only accepted when object_type is contact; using either with any other object type returns 400.

Object types Use the object type exactly as it is defined in your account, for example vehicle for a custom object of that name, or contact for contacts. An object type that does not exist in your account returns 400.

Filtering by associated object type Use type to restrict the response to one or more associated object types, for example ?type=contact&type=garage. Up to 5 types can be requested per call; more returns 400. When type is omitted, associations of every type are returned.

Pagination Results are returned 20 per page. The page size is fixed and cannot be changed. Increase offset by 20 to walk through the pages until has_more is false. An offset beyond the last record returns an empty items array with has_more set to false.

Working with contacts

contact is supported both as the source object_type and as an associated object type.
An id, ext_id, email or sms that matches no contact returns 404.
If several contacts share the same ext_id, email or sms, identify the contact by id to be sure of which one is used.
Contacts returned in items carry all of the contact’s attributes, with attribute keys in lowercase — email, first_name, last_name, sms, ext_id, and any other contact attribute lowercased.
For contacts, ext_id, created_at and updated_at are not returned on object. A contact’s external ID is available as attributes.ext_id when it is set.

Authentication

api-keystring

The API key should be passed in the request headers as api-key for authentication.

AuthorizationBearer

OAuth 2.0 client_credentials (machine-to-machine) grant. Exchange your app’s client_id/client_secret for a short-lived Bearer token.

Path parameters

object_typestringRequired

Object type of the source record, exactly as defined in your account. Accepts any object type defined in the account, for example a custom object type or contact.

Query parameters

idlongOptional>=1

Internal Brevo ID of the source record. Must be a positive integer. Provide exactly one of id, ext_id, email or sms.

ext_idstringOptional

External ID of the source record in your system. Provide exactly one of id, ext_id, email or sms.

emailstringOptional

Email address of the source contact. Only accepted when object_type is contact. Provide exactly one of id, ext_id, email or sms.

smsstringOptional

Phone number of the source contact, including the country code. It may be given with or without a leading +; percent-encode the + as %2B, because a literal + in a query string is read as a space. Only accepted when object_type is contact. Provide exactly one of id, ext_id, email or sms.

typelist of stringsOptional

Restricts the response to the given associated object types. Repeat the parameter to request several types, for example ?type=contact&type=garage. Maximum 5 types per call. Associations of every type are returned when omitted.

offsetlongOptional>=0Defaults to 0

Number of records to skip before the first record of the page. Defaults to 0. Increase by 20 to fetch the next page.

Response

A page of records associated with the source record.

has_morebooleanOptional

true when at least one more associated record exists after this page.

itemslist of objectsOptional

Associated records for this page, up to 20 per page. Fewer when the last page is reached, empty when the source record has no matching associations.

offsetlongOptional

The offset that was requested.

Errors

400

Bad Request Error

404

Not Found Error

500

Internal Server Error