> For the complete documentation index, see [llms.txt](https://docs.usepylon.com/pylon-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/custom-objects.md).

# Custom Objects

## List custom objects

> Returns paginated custom objects of the given type.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"responses":{"GetCustomObjectsResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCustomObjectsResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetCustomObjectsResponseBody":{"properties":{"data":{"items":{"$ref":"#/components/schemas/APICustomObject"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"type":"object"},"APICustomObject":{"properties":{"created_at":{"description":"When the object was created.","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values keyed by field slug. Relationship-typed fields are excluded here and returned in the `relations` field instead.","type":"object"},"id":{"description":"The ID of the custom object.","type":"string"},"name":{"description":"The name of the custom object.","type":"string"},"relations":{"description":"Relationships from this object to other objects, sourced from relationship-typed custom fields.","items":{"$ref":"#/components/schemas/APIObjectRelation"},"type":"array"},"type":{"description":"The type slug of the custom object.","type":"string"},"updated_at":{"description":"When the object was last updated.","type":"string"}},"type":"object"},"CustomFieldValue":{"properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"type":"object"},"APIObjectRelation":{"properties":{"object_id":{"description":"The ID of the related object.","type":"string"},"object_type":{"description":"The type of the related object (e.g. \"account\", \"contact\", \"issue\").","type":"string"}},"title":"APIObjectRelation is a single edge from a custom object to another object, sourced from a relationship-typed custom field.","type":"object"},"Pagination":{"properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/custom-objects/{type}":{"get":{"description":"Returns paginated custom objects of the given type.\n\n**Rate limit:** 60 requests per minute","operationId":"GetCustomObjects","parameters":[{"description":"The type slug of the custom object (e.g. \"companies\").","in":"path","name":"type","required":true,"schema":{"type":"string"}},{"description":"Pagination cursor for the next page.","in":"query","name":"cursor","schema":{"type":"string"}},{"description":"Number of results per page. Defaults to 25, max 100.","in":"query","name":"limit","schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"$ref":"#/components/responses/GetCustomObjectsResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"List custom objects","tags":["custom-objects"]}}}}
```

## Get a custom object

> Returns a single custom object by ID, including its custom field values.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"responses":{"GetCustomObjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCustomObjectResponseBody"}}},"description":""},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetCustomObjectResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/APICustomObject"},"request_id":{"type":"string"}},"type":"object"},"APICustomObject":{"properties":{"created_at":{"description":"When the object was created.","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values keyed by field slug. Relationship-typed fields are excluded here and returned in the `relations` field instead.","type":"object"},"id":{"description":"The ID of the custom object.","type":"string"},"name":{"description":"The name of the custom object.","type":"string"},"relations":{"description":"Relationships from this object to other objects, sourced from relationship-typed custom fields.","items":{"$ref":"#/components/schemas/APIObjectRelation"},"type":"array"},"type":{"description":"The type slug of the custom object.","type":"string"},"updated_at":{"description":"When the object was last updated.","type":"string"}},"type":"object"},"CustomFieldValue":{"properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"type":"object"},"APIObjectRelation":{"properties":{"object_id":{"description":"The ID of the related object.","type":"string"},"object_type":{"description":"The type of the related object (e.g. \"account\", \"contact\", \"issue\").","type":"string"}},"title":"APIObjectRelation is a single edge from a custom object to another object, sourced from a relationship-typed custom field.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/custom-objects/{type}/{id}":{"get":{"description":"Returns a single custom object by ID, including its custom field values.\n\n**Rate limit:** 60 requests per minute","operationId":"GetCustomObject","parameters":[{"description":"The type slug of the custom object (e.g. \"companies\").","in":"path","name":"type","required":true,"schema":{"type":"string"}},{"description":"The ID of the custom object.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetCustomObjectResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get a custom object","tags":["custom-objects"]}}}}
```

## Search for custom objects by a given filter

> Currently, the following fields are filterable for custom objects:\
> \
> \* name. Allowed operators: \`equals\`, \`in\`, \`not\_in\`, \`string\_contains\`, \`string\_does\_not\_contain\`, \`is\_set\`, \`is\_unset\`\
> \
> \* created\_at (in RFC3339 format). Allowed operators: \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\`\
> \
> \* updated\_at (in RFC3339 format). Allowed operators: \`time\_is\_after\`, \`time\_is\_before\`, \`time\_range\`\
> \
> \* custom fields (pass in the slug of the custom field)\
> \
> \*\*Rate limit:\*\* 20 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"SearchCustomObjectsRequest":{"properties":{"cursor":{"description":"The cursor to use for pagination.","type":"string"},"filter":{"$ref":"#/components/schemas/Filter"},"limit":{"description":"The number of results to fetch. Defaults to 25, max 100.","format":"int64","type":"integer"}},"type":"object"},"Filter":{"properties":{"field":{"description":"The field for this filter.  For allowed fields, see the documentation for\n\nthe specific endpoint you are using.\n\nFor non-compound filters (any operators other than \"and\" or \"or\"),\n\nField must be set, along with either Value or Values, depending on the operator.","type":"string"},"operator":{"description":"The operator for this filter.\n\n`equals`: Matches objects that are exactly equal to the value in the field.\n\n`not_equals`: Matches objects that are not exactly equal to the value in the field.\n\n`contains`: For a multi-valued field, such as tags, this operator will match  objects that contain any of the values in the field.\n\n`does_not_contain`: For a multi-valued field, such as tags, this operator will match  objects that do not contain any of the values in the field.\n\n`in`: Matches objects if the field is one of several possible values,  as specified in the values array.\n\n`not_in`: Matches objects if the field is none of several possible values,  as specified in the values array.\n\n`and`: Matches objects only if all subfilters match.\n\n`or`: Matches objects if any subfilter matches.\n\n`time_is_after`: Matches objects if the field is after the given time.\n\n`time_is_before`: Matches objects if the field is before the given time.\n\n`time_range`: Matches objects if the field is between the given times.\n\n`string_contains`: Matches objects if the field contains the given string.\n\n`string_does_not_contain`: Matches objects if the field does not contain the given string.\n\n`is_set`: Matches objects if the field is set.\n\n`is_unset`: Matches objects if the field is unset.\n\n`greater_than`: Matches objects if the numeric field is greater than the given value.\n\n`less_than`: Matches objects if the numeric field is less than the given value.\n\n`greater_than_or_equals`: Matches objects if the numeric field is greater than or equal to the given value.\n\n`less_than_or_equals`: Matches objects if the numeric field is less than or equal to the given value.","enum":["equals","not_equals","contains","does_not_contain","in","not_in","and","or","time_is_after","time_is_before","time_range","string_contains","string_does_not_contain","is_set","is_unset","greater_than","less_than","greater_than_or_equals","less_than_or_equals"],"type":"string"},"subfilters":{"description":"Sub-filters for this filter.  Valid only when operator is \"and\" or \"or\".\n\nThe maximum allowed depth for a tree of filters is 3.","items":{"$ref":"#/components/schemas/Filter"},"type":"array"},"value":{"description":"The value for this filter. Only used for single-valued operators\n\n(\"equals\", \"not_equals\", \"contains\", \"does_not_contain\")","type":"string"},"values":{"description":"The values for this filter. Only used for multi-valued operators (\"in\", \"not_in\").","items":{"type":"string"},"type":"array"}},"required":["operator","field"],"type":"object"},"SearchCustomObjectsResponseBody":{"properties":{"data":{"items":{"$ref":"#/components/schemas/APICustomObject"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"type":"object"},"APICustomObject":{"properties":{"created_at":{"description":"When the object was created.","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values keyed by field slug. Relationship-typed fields are excluded here and returned in the `relations` field instead.","type":"object"},"id":{"description":"The ID of the custom object.","type":"string"},"name":{"description":"The name of the custom object.","type":"string"},"relations":{"description":"Relationships from this object to other objects, sourced from relationship-typed custom fields.","items":{"$ref":"#/components/schemas/APIObjectRelation"},"type":"array"},"type":{"description":"The type slug of the custom object.","type":"string"},"updated_at":{"description":"When the object was last updated.","type":"string"}},"type":"object"},"CustomFieldValue":{"properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"type":"object"},"APIObjectRelation":{"properties":{"object_id":{"description":"The ID of the related object.","type":"string"},"object_type":{"description":"The type of the related object (e.g. \"account\", \"contact\", \"issue\").","type":"string"}},"title":"APIObjectRelation is a single edge from a custom object to another object, sourced from a relationship-typed custom field.","type":"object"},"Pagination":{"properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}},"responses":{"SearchCustomObjectsResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCustomObjectsResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/custom-objects/{type}/search":{"post":{"description":"Currently, the following fields are filterable for custom objects:\n\n* name. Allowed operators: `equals`, `in`, `not_in`, `string_contains`, `string_does_not_contain`, `is_set`, `is_unset`\n\n* created_at (in RFC3339 format). Allowed operators: `time_is_after`, `time_is_before`, `time_range`\n\n* updated_at (in RFC3339 format). Allowed operators: `time_is_after`, `time_is_before`, `time_range`\n\n* custom fields (pass in the slug of the custom field)\n\n**Rate limit:** 20 requests per minute","operationId":"SearchCustomObjects","parameters":[{"description":"The type slug of the custom object (e.g. \"companies\").","in":"path","name":"type","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCustomObjectsRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/SearchCustomObjectsResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Search for custom objects by a given filter","tags":["custom-objects"]}}}}
```

## Create a custom object

> Creates a new custom object instance of the given type. To link the object to an account, pass the built-in Account relationship field in \`custom\_fields\`: \`{"name":"Example","custom\_fields":{"account":{"value":"account\_uuid"}}}\`.\
> \
> \*\*Rate limit:\*\* 20 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"CreateCustomObjectRequestBody":{"properties":{"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values to set on the object, keyed by field slug. To link the object to an account, pass the built-in Account relationship field as `custom_fields.account.value`, for example `{\"custom_fields\":{\"account\":{\"value\":\"account_uuid\"}}}`.","type":"object"},"name":{"description":"The name of the custom object.","type":"string"}},"required":["name"],"type":"object"},"CustomFieldValue":{"properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"type":"object"},"CreateCustomObjectResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/APICustomObject"},"request_id":{"type":"string"}},"type":"object"},"APICustomObject":{"properties":{"created_at":{"description":"When the object was created.","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values keyed by field slug. Relationship-typed fields are excluded here and returned in the `relations` field instead.","type":"object"},"id":{"description":"The ID of the custom object.","type":"string"},"name":{"description":"The name of the custom object.","type":"string"},"relations":{"description":"Relationships from this object to other objects, sourced from relationship-typed custom fields.","items":{"$ref":"#/components/schemas/APIObjectRelation"},"type":"array"},"type":{"description":"The type slug of the custom object.","type":"string"},"updated_at":{"description":"When the object was last updated.","type":"string"}},"type":"object"},"APIObjectRelation":{"properties":{"object_id":{"description":"The ID of the related object.","type":"string"},"object_type":{"description":"The type of the related object (e.g. \"account\", \"contact\", \"issue\").","type":"string"}},"title":"APIObjectRelation is a single edge from a custom object to another object, sourced from a relationship-typed custom field.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}},"responses":{"CreateCustomObjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomObjectResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/custom-objects/{type}":{"post":{"description":"Creates a new custom object instance of the given type. To link the object to an account, pass the built-in Account relationship field in `custom_fields`: `{\"name\":\"Example\",\"custom_fields\":{\"account\":{\"value\":\"account_uuid\"}}}`.\n\n**Rate limit:** 20 requests per minute","operationId":"CreateCustomObject","parameters":[{"description":"The type slug of the custom object (e.g. \"companies\").","in":"path","name":"type","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomObjectRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/CreateCustomObjectResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Create a custom object","tags":["custom-objects"]}}}}
```

## Update a custom object

> Updates a custom object. Only provided fields are modified. To update the linked account, pass the built-in Account relationship field in \`custom\_fields\`: \`{"custom\_fields":{"account":{"value":"account\_uuid"}}}\`.\
> \
> \*\*Rate limit:\*\* 20 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"UpdateCustomObjectRequestBody":{"properties":{"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values to set on the object, keyed by field slug. To update the linked account, pass the built-in Account relationship field as `custom_fields.account.value`, for example `{\"custom_fields\":{\"account\":{\"value\":\"account_uuid\"}}}`.","type":"object"},"name":{"description":"The name of the custom object.","type":"string"}},"type":"object"},"CustomFieldValue":{"properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"type":"object"},"UpdateCustomObjectResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/APICustomObject"},"request_id":{"type":"string"}},"type":"object"},"APICustomObject":{"properties":{"created_at":{"description":"When the object was created.","type":"string"},"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values keyed by field slug. Relationship-typed fields are excluded here and returned in the `relations` field instead.","type":"object"},"id":{"description":"The ID of the custom object.","type":"string"},"name":{"description":"The name of the custom object.","type":"string"},"relations":{"description":"Relationships from this object to other objects, sourced from relationship-typed custom fields.","items":{"$ref":"#/components/schemas/APIObjectRelation"},"type":"array"},"type":{"description":"The type slug of the custom object.","type":"string"},"updated_at":{"description":"When the object was last updated.","type":"string"}},"type":"object"},"APIObjectRelation":{"properties":{"object_id":{"description":"The ID of the related object.","type":"string"},"object_type":{"description":"The type of the related object (e.g. \"account\", \"contact\", \"issue\").","type":"string"}},"title":"APIObjectRelation is a single edge from a custom object to another object, sourced from a relationship-typed custom field.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}},"responses":{"UpdateCustomObjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomObjectResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/custom-objects/{type}/{id}":{"patch":{"description":"Updates a custom object. Only provided fields are modified. To update the linked account, pass the built-in Account relationship field in `custom_fields`: `{\"custom_fields\":{\"account\":{\"value\":\"account_uuid\"}}}`.\n\n**Rate limit:** 20 requests per minute","operationId":"UpdateCustomObject","parameters":[{"description":"The type slug of the custom object (e.g. \"companies\").","in":"path","name":"type","required":true,"schema":{"type":"string"}},{"description":"The ID of the custom object.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomObjectRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateCustomObjectResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Update a custom object","tags":["custom-objects"]}}}}
```

## Bulk update custom objects

> Applies the same update to multiple custom objects of the given type in a single request. Pass between 1 and 100 IDs and the custom field values to set; only the provided fields are modified on each object. To update the linked account, pass the built-in Account relationship field in \`custom\_fields\`: \`{"ids":\["object\_uuid"],"custom\_fields":{"account":{"value":"account\_uuid"}}}\`. To unset a field, pass its slug with an empty value.\
> \
> \*\*Rate limit:\*\* 20 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"UpdateCustomObjectsRequest":{"properties":{"custom_fields":{"additionalProperties":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"Custom field values to apply to every listed custom object, keyed by field slug. To unset a field, pass its slug with an empty value.","type":"object"},"ids":{"description":"The IDs of the custom objects to update. Must be between 1 and 100 IDs.","items":{"type":"string"},"type":"array"}},"required":["ids"],"type":"object"},"CustomFieldValue":{"properties":{"slug":{"description":"The slug of the custom field.","type":"string"},"value":{"description":"The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.","type":"string"},"values":{"description":"The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.","items":{"type":"string"},"type":"array"}},"type":"object"},"UpdateCustomObjectsResponseBody":{"properties":{"request_id":{"type":"string"},"success":{"type":"boolean"},"updated_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}},"responses":{"UpdateCustomObjectsResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomObjectsResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/custom-objects/{type}":{"patch":{"description":"Applies the same update to multiple custom objects of the given type in a single request. Pass between 1 and 100 IDs and the custom field values to set; only the provided fields are modified on each object. To update the linked account, pass the built-in Account relationship field in `custom_fields`: `{\"ids\":[\"object_uuid\"],\"custom_fields\":{\"account\":{\"value\":\"account_uuid\"}}}`. To unset a field, pass its slug with an empty value.\n\n**Rate limit:** 20 requests per minute","operationId":"UpdateCustomObjects","parameters":[{"description":"The type slug of the custom object (e.g. \"opportunity\").","in":"path","name":"type","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomObjectsRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateCustomObjectsResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Bulk update custom objects","tags":["custom-objects"]}}}}
```

## Delete a custom object

> Deletes a custom object instance.\
> \
> \*\*Rate limit:\*\* 20 requests per minute

```json
{"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"responses":{"DeleteCustomObjectResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteCustomObjectResponseBody"}}},"description":""},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"DeleteCustomObjectResponseBody":{"properties":{"request_id":{"type":"string"}},"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/custom-objects/{type}/{id}":{"delete":{"description":"Deletes a custom object instance.\n\n**Rate limit:** 20 requests per minute","operationId":"DeleteCustomObject","parameters":[{"description":"The type slug of the custom object (e.g. \"companies\").","in":"path","name":"type","required":true,"schema":{"type":"string"}},{"description":"The ID of the custom object.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/DeleteCustomObjectResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Delete a custom object","tags":["custom-objects"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.usepylon.com/pylon-docs/developer/api/api-reference/custom-objects.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.