{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Custom Objects Via API - Development Portal | Outreach","description":"Outreach extensibility development and documentation portal","siteUrl":"https://developers.outreach.io","keywords":"outreach developer portal, api documentation, api reference docs, sdk documentation","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"custom-objects-via-api","__idx":0},"children":["Custom Objects via API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Custom Objects are a way to store custom data in Outreach. You can use Custom Objects to store data that is not natively supported by Outreach, such as product information, customer data, or any other custom data that you need to store."," ","They are configurable in the Outreach Application. The public API allows you to list, get, create, update and delete custom object records."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"accessing-custom-object-endpoints","__idx":1},"children":["Accessing Custom Object Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Outreach API, custom objects are under their specific paths ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/v2/customObjects"]},". The custom objects and their fields are identifier by their ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["internal name"]}," that"," ","your administrator had chosen when configuring the object in the Outreach Application. That also means that when a relationship refers"," ","to a custom object its type is the internal name of the referred custom object."," ","As for standard resources, they have their own API Reference documentation. It is accessible through ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developers.outreach.io/apps/custom-objects-schema","target":"_blank"},"children":["an authenticated portal"]},". This documentation is automatically generated and uploaded daily based on the custom object schemas built by your administrators. Therefore you may expect a delay between a new custom object creation or a change to its configuration and its availability in the API Reference (maximum 1 day)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without delay, you can find all the custom objects with their attributes and relationships by calling the schema endpoint. They will be present next to standard resources."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/schema\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"$schema\": \"http://json-schema.org/draft-07/hyper-schema#\",\n    \"definitions\": {\n        \"account\": {\n            \"$schema\": \"http://json-schema.org/draft-07/hyper-schema#\",\n            \"definitions\": {\n                \"name\": {\n                    \"filterable\": true,\n                    \"sortable\": true,\n                    \"type\": \"string\"\n                },\n                // ...\n            },\n            // ...\n            \"stability\": \"prototype\",\n            \"type\": \"object\"\n        },\n        \"myCustomObject\": {\n            \"$schema\": \"http://json-schema.org/draft-07/hyper-schema#\",\n            \"definitions\": {\n                 \"my_object_name\": {\n                    \"filterable\": true,\n                    \"sortable\": true,\n                    \"type\": \"string\"\n                },\n                // ...\n            },\n            // ...\n            \"stability\": \"prototype\",\n            \"type\": \"object\"\n        }\n    }\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note: the schema endpoint works for unauthenticated users too. If the request is not authenticated, the schema will not contain"," ","your organization's custom objects."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"crud-operations-on-custom-objects","__idx":2},"children":["CRUD operations on custom objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Listing, getting, creating, updating and deleting custom object records is done in a similar ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/making-requests"},"children":["way to standard resources"]},". Let's assume a custom object with internal name ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vehicles"]}," was defined using Outreach Application."," ",{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/vehicles-custom-object-definition.2504a4b639af1895619fd49f52cc4942de4a4b97a9569a28d71a2f580e56b600.9c1bb791.png","alt":"Vehicles Definition"},"children":[]}," ","It has several fields, including a reference to a prospect with internal name ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["main_driver"]},"."," ",{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/vehicles-fields-definition.9ccb94108f18f4730222a617b06f97f506afc7c7116ea18730ed4844a6fc90a7.9c1bb791.png","alt":"Vehicles Fields"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here are the endpoints available:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List All Custom Object Records, response includes pagination as standard resources."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": [\n        {\n            \"type\": \"vehicles\",\n            \"id\": 123456,\n            \"attributes\": {\n                \"createdAt\": \"2024-07-25T13:18:30.736332Z\",\n                \"vehicle_name\": \"DeLorean\",\n                \"speed\": \"130mph\",\n                \"updatedAt\": \"2024-07-25T13:18:30.736332Z\"\n            },\n            \"relationships\": {\n                \"main_driver\": {\n                    \"data\": {\n                        \"type\": \"prospect\",\n                        \"id\": 123\n                    }\n                }\n            },\n            \"links\": {\n                \"self\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles/123456\"\n            }\n        },\n        // ...\n    ],\n    \"meta\": {\n        \"count\": 10,\n        \"count_truncated\": false\n    },\n    \"links\": {\n        \"first\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles?page%5Bsize%5D=50\",\n        \"next\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles?page%5Bafter%5D=Wzk3Mjc1XQ%3D%3D&page%5Bsize%5D=50\"\n    }\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Get a Custom Object Record"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles/123456\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": {\n        \"type\": \"special_customers\",\n        \"id\": 123456,\n        \"attributes\": {\n            // ...\n         },\n        \"relationships\": {\n            // ...\n        },\n        \"links\": {\n            \"self\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles/123456\"\n        }\n    },\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a Custom Object Record (similar response as for GET one)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST https://api.outreach.io/api/v2/customObjects/vehicles\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["with request body"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": {\n        \"type\": \"vehicles\",\n        \"attributes\": {\n            \"vehicle_name\": \"Ford T\",\n            \"speed\": \"45mph\"\n        },\n        \"relationships\": {\n            \"main_driver\": {\n                \"data\": {\n                    \"type\": \"prospect\",\n                    \"id\": 4321\n                }\n            }\n        }\n    }\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update a Custom Object Record (similar response as for GET one)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PATCH https://api.outreach.io/api/v2/customObjects/vehicles/123456\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["with request body"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": {\n        \"type\": \"vehicles\",\n        \"id\": 123456,\n        \"attributes\": {\n            \"speed\": \"117mph\"\n        }\n\n    }\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete a Custom Object Record (response is empty, HTTP status 204)"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"DELETE https://api.outreach.io/api/v2/customObjects/vehicles/123456\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"filtering-and-sorting","__idx":3},"children":["Filtering and sorting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the LIST endpoints you can use filters and sort in a similar way as for standard resources. The filters are based on the fields of the custom object."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles?filter[age]=0..10&filter[main_driver][id]=123&sort=-vehicle_name\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure to read about filtering and sorting in APIv2 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/making-requests/#filter-and-sort"},"children":["filter and sort"]}," as the syntax is the same for custom objects."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One important point is when filtering by relationship, as for standard object, you can always filter by the referred object id. You can also target different attributes depending and the type of the relationship:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["for prospect, opportunity, account: name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["for user: email and name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["for custom objects: the field marked as display name."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's say now that our ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vehicles"]}," custom object has a reference to a custom object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vehicle_brands"]}," with a field ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," marked as display name."," ",{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/vehicles-with-brand-field.c891e8362535426dcd453ed4f4ae3a0a6c4aedbd4274e6234f25dc9a34f65ea8.9c1bb791.png","alt":"Vehicles With brand"},"children":[]}," ",{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/vehicle-brands-fields-definition.a328f9791fcae354c93c59e2c3e97a0414f348d7dd93bbc0fecbba2aebeb0b06.9c1bb791.png","alt":"Vehicle Brands"},"children":[]}," ","If we would like to filter vehicles by the brand name, we would do:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"LIST https://api.outreach.io/api/v2/customObjects/vehicles?filter[brand][name]=DMC\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": [\n        {\n            \"type\": \"vehicles\",\n            \"id\": 123456,\n            \"attributes\": {\n                \"createdAt\": \"2024-07-25T13:18:30.736332Z\",\n                \"vehicle_name\": \"DeLorean\",\n                \"speed\": \"117mph\",\n                \"updatedAt\": \"2024-07-25T13:18:30.736332Z\"\n            },\n            \"relationships\": {\n                \"main_driver\": {\n                    \"data\": {\n                        \"type\": \"prospect\",\n                        \"id\": 123\n                    }\n                },\n                \"brand\": {\n                    \"data\": {\n                        \"type\": \"vehicle_brands\",\n                        \"id\": 1\n                    }\n                }\n            },\n            \"links\": {\n                \"self\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles/123456\"\n            }\n        }\n    ],\n    \"meta\": {\n        \"count\": 1,\n        \"count_truncated\": false\n    },\n    \"links\": {\n        \"first\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles?page%5Bsize%5D=50?filter[brand][name]=DMC\",\n    }\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the schema of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vehicle_brands"]}," changes and has a different display name, the filter will not work anymore. You need to use the field newly marked as display name. If you would like the filter to work regardless of the display name, you need to filter by the id of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vehicle_brands"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"including-related-resources","__idx":4},"children":["Including Related Resources"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure to read about ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/making-requests/#include-related-resources"},"children":["including related resources in APIv2"]},"."," ","Similarly to standard object, to include a resource you will be using the reference field internal name. In the case of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vehicles"]}," where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["main_driver"]}," is a reference to a prospect, you would do:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles/123456?include=main_driver\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\": {\n        \"type\": \"vehicles\",\n        \"id\": 123456,\n        \"attributes\": {\n            \"createdAt\": \"2024-07-25T13:18:30.736332Z\",\n            \"vehicle_name\": \"DeLorean\",\n            \"speed\": \"117mph\",\n            \"updatedAt\": \"2024-07-25T13:18:30.736332Z\"\n        },\n        \"relationships\": {\n            \"main_driver\": {\n                \"data\": {\n                    \"type\": \"prospect\",\n                    \"id\": 123\n                }\n            },\n            \"brand\": {\n                \"data\": {\n                    \"type\": \"vehicle_brands\",\n                    \"id\": 1\n                }\n            }\n        },\n        \"links\": {\n            \"self\": \"https://api.outreach-staging.com/api/v2/customObjects/vehicles/123456\"\n        }\n    },\n    \"included\": [\n        {\n            \"type\": \"prospect\",\n            \"id\": 123,\n            \"attributes\": {\n                \"name\": \"John\"\n            }\n        }\n    ]\n}\n","lang":"json5"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can only go one level deep to include related resources that are custom objects. That means that the following would not work:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles?include=brand.another_object\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Meanwhile this would:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles?include=main_driver.account\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sparse-fieldsets","__idx":5},"children":["Sparse Fieldsets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure to read about ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/making-requests/#specify-sparse-fieldsets"},"children":["sparse fieldsets in APIv2"]},". Custom objects support sparse fieldsets in the same way as standard resources."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here you target resources by their type (internal name of the custom object) and the fields by their internal name."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET https://api.outreach.io/api/v2/customObjects/vehicles/123456?include=brand&fields[vehicle_brands]=name&fields[vehicles]=name\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json5","header":{"controls":{"copy":{}}},"source":"{\n    \"data\":\n    {\n        \"type\": \"campaigns\",\n        \"id\": 123456,\n        \"attributes\": {\n            \"name\": \"DeLorean\"\n        }\n    },\n    \"included\": [\n        {\n            \"type\": \"vehicle_brands\",\n            \"id\": 1,\n            \"attributes\": {\n                \"name\": \"DMC\"\n            }\n        }\n    ]\n}\n","lang":"json5"},"children":[]}]},"headings":[{"value":"Custom Objects via API","id":"custom-objects-via-api","depth":1},{"value":"Accessing Custom Object Endpoints","id":"accessing-custom-object-endpoints","depth":2},{"value":"CRUD operations on custom objects","id":"crud-operations-on-custom-objects","depth":2},{"value":"Filtering and sorting","id":"filtering-and-sorting","depth":2},{"value":"Including Related Resources","id":"including-related-resources","depth":2},{"value":"Sparse Fieldsets","id":"sparse-fieldsets","depth":2}],"frontmatter":{"seo":{"title":"Custom Objects Via API - Development Portal | Outreach"}},"lastModified":"2026-05-22T19:00:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api/custom-objects","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}