> For the complete documentation index, see [llms.txt](https://knowledge.out-smart.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledge.out-smart.com/openapi/relations.md). # Relations ## Get relations > Use this endpoint to get relations from the OutSmart account. \ > Each relation record can contain the following data:\ > \ > \| Parameter | Required | Description |\ > \| --- | --- | --- |\ > \| debtor\_number | Y | Unique id of the relation |\ > \| name | Y | Name of the relation |\ > \| contact | N | Name om the main contactperson of the relation |\ > \| phone\_number | N | Phone number |\ > \| email | N | Contact email address |\ > \| email\_workorder | N | Email address used when sending workorder to the customer |\ > \| street | Y | Relation address street name |\ > \| house\_number | N | Relation address house number |\ > \| postal\_code | Y | Relation address postal code |\ > \| city | Y | Relation address city |\ > \| country | N | Relation address country code |\ > \| remark | N | Text field for any additional remarks on the relation |\ > \| latitude | N | Relation address latitude coordinate |\ > \| longitude | N | Relation address longitude coordinate |\ > \| external\_id | N | External id field, often used for storing id reference from external software |\ > \| debtor\_number\_invoice | N | |\ > \| kvk\_number | N | Chamber of commerce number |\ > \| vat\_number | N | VAT identification number |\ > \| debtor\_type | N | Indicates the relation type, for example: customer, lead etc |\ > \| language | N | Language selection, value indicated with a country code. Example 'nl' for Dutch |\ > \| accountmanager | N | |\ > \| mobile | N | Mobile phone number |\ > \| status | N | |\ > \| active | N | Indication whether the relation is active or not. Value 0 for incactive, 1 for active |\ > \| pgp\_code | N | |\ > \| source | N | |\ > \| lead\_phase | N | |\ > \| lead\_score | N | |\ > \| lead\_value | N | |\ > \| loss\_reason | N | |\ > \| lead\_value\_recurring | N | |\ > \| marketing\_opt\_out | N | |\ > \| discount\_sales | N | Discount percentage applied for this relation. Integer value |\ > \| created\_at | N | Datetime value indicating when the relation was created. Date format: YYYY-MM-DD HH:mm:ss |\ > \| modified\_at | N | Datetime value indicating the relation was last modified. Dat format: YYYY-MM-DD HH:mm:ss |\ > \| created\_by | N | Employee number of who created the relation |\ > \| modified\_by | N | Employee number of the last employee who modified the relation data |\ > \ > \*\*Freefields\*\*\ > \ > Additional freefields can be added to the relation data. To include these in the results, add the URL parameter \`includeFreefields\` with value \`true\`. Freefields will only be added to the results when declared, use the \[Freefields]\() endpoint to see which fields have been set. Freefields are numbered 1-50.\ > \ > \*\*Filtering\*\*\ > \ > This endpoint supports filtering options. Read the section on applying filters to the request \[here]\(). \ > Filters can be applied to the following field values:\ > \ > \- name\ > \- debtor\_number\ > \- contact\ > \- phone\ > \- mobile\ > \- email\ > \- werkbonmailto (filters on email\_workorder)\ > \- street\ > \- streetno\ > \- zip\ > \- city\ > \- latitude\ > \- longitude\ > \- external\_id\ > \- modified\_at\ > \- created\_at\ > \- debtor\_type\ > \- active\ > \ > \ > \*\*Example with filters\*\*\ > \ > In order to get specific results, multiple filters can be applied by adding multiple \`key\[]\`, \`value\[]\`, and \`operator\[]\` URL parameters. For example with the request below:\ > \ > {api\_url}/relations/?token={client\_token}\&software\_token={software\_token}\&key\\\[\\]=modified\_at\&value\\\[\\]=2022-01-01 00:00:00\&operator\\\[\\]=ge\&key\\\[\\]=active\&value\\\[\\]=eq\&operator\\\[\\]=1\ > \ > This would get all relations that have been modified after new years 2022, and are set to be active. This example uses 2 filters:\ > \ > \- \`modified\_at\` value is checked to 'ge' (greater equals) the value 2022-01-01\ > \- \`active\` value is check to 'eq' (equals) the value 1\ > \ > \ > Additional filters can by applied by adding more of the filter URL parameters. Do note that currently all added filters will be applied as AND, there is currently no way to check 2 filters with OR keyword. So all the applied filters will have to be checked as true on the relations returned. ```json {"openapi":"3.1.0","info":{"title":"OpenApi","version":"1.0.0"},"servers":[{"url":"{{api_url}}"},{"url":"https://www.werkbonapp.nl"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/relations/":{"get":{"summary":"Get relations","parameters":[{"name":"token","in":"query","description":"Client token, unique to an Outsmart account","schema":{"type":"string"}},{"name":"software_token","in":"query","description":"Software token","schema":{"type":"string"}},{"name":"key[]","in":"query","description":"Filter parameter. Name of the field to apply filter to","schema":{"type":"string"}},{"name":"value[]","in":"query","description":"Filter parameter. Search value for the filter","schema":{"type":"string"}},{"name":"operator[]","in":"query","description":"Filter parameter. Operator applied to the filter query","schema":{"type":"string"}},{"name":"includeFreefields","in":"query","description":"Boolean value. Determines whether freefields are included in the response. Default value is false","schema":{"type":"string"}}],"responses":{"200":{"description":"Response_200"}},"tags":["Relations"],"description":"Use this endpoint to get relations from the OutSmart account. \nEach relation record can contain the following data:\n\n| Parameter | Required | Description |\n| --- | --- | --- |\n| debtor_number | Y | Unique id of the relation |\n| name | Y | Name of the relation |\n| contact | N | Name om the main contactperson of the relation |\n| phone_number | N | Phone number |\n| email | N | Contact email address |\n| email_workorder | N | Email address used when sending workorder to the customer |\n| street | Y | Relation address street name |\n| house_number | N | Relation address house number |\n| postal_code | Y | Relation address postal code |\n| city | Y | Relation address city |\n| country | N | Relation address country code |\n| remark | N | Text field for any additional remarks on the relation |\n| latitude | N | Relation address latitude coordinate |\n| longitude | N | Relation address longitude coordinate |\n| external_id | N | External id field, often used for storing id reference from external software |\n| debtor_number_invoice | N | |\n| kvk_number | N | Chamber of commerce number |\n| vat_number | N | VAT identification number |\n| debtor_type | N | Indicates the relation type, for example: customer, lead etc |\n| language | N | Language selection, value indicated with a country code. Example 'nl' for Dutch |\n| accountmanager | N | |\n| mobile | N | Mobile phone number |\n| status | N | |\n| active | N | Indication whether the relation is active or not. Value 0 for incactive, 1 for active |\n| pgp_code | N | |\n| source | N | |\n| lead_phase | N | |\n| lead_score | N | |\n| lead_value | N | |\n| loss_reason | N | |\n| lead_value_recurring | N | |\n| marketing_opt_out | N | |\n| discount_sales | N | Discount percentage applied for this relation. Integer value |\n| created_at | N | Datetime value indicating when the relation was created. Date format: YYYY-MM-DD HH:mm:ss |\n| modified_at | N | Datetime value indicating the relation was last modified. Dat format: YYYY-MM-DD HH:mm:ss |\n| created_by | N | Employee number of who created the relation |\n| modified_by | N | Employee number of the last employee who modified the relation data |\n\n**Freefields**\n\nAdditional freefields can be added to the relation data. To include these in the results, add the URL parameter `includeFreefields` with value `true`. Freefields will only be added to the results when declared, use the [Freefields](https://documenter.getpostman.com/view/3100119/UVRDG5v7#a4d1b560-dd2b-4936-9ffe-80aee3514507) endpoint to see which fields have been set. Freefields are numbered 1-50.\n\n**Filtering**\n\nThis endpoint supports filtering options. Read the section on applying filters to the request [here](https://documenter.getpostman.com/view/3100119/UVRDG5v7#advanced-filters). \nFilters can be applied to the following field values:\n\n- name\n- debtor_number\n- contact\n- phone\n- mobile\n- email\n- werkbonmailto (filters on email_workorder)\n- street\n- streetno\n- zip\n- city\n- latitude\n- longitude\n- external_id\n- modified_at\n- created_at\n- debtor_type\n- active\n \n\n**Example with filters**\n\nIn order to get specific results, multiple filters can be applied by adding multiple `key[]`, `value[]`, and `operator[]` URL parameters. For example with the request below:\n\n{api_url}/relations/?token={client_token}&software_token={software_token}&key\\[\\]=modified_at&value\\[\\]=2022-01-01 00:00:00&operator\\[\\]=ge&key\\[\\]=active&value\\[\\]=eq&operator\\[\\]=1\n\nThis would get all relations that have been modified after new years 2022, and are set to be active. This example uses 2 filters:\n\n- `modified_at` value is checked to 'ge' (greater equals) the value 2022-01-01\n- `active` value is check to 'eq' (equals) the value 1\n \n\nAdditional filters can by applied by adding more of the filter URL parameters. Do note that currently all added filters will be applied as AND, there is currently no way to check 2 filters with OR keyword. So all the applied filters will have to be checked as true on the relations returned."}}}} ``` ## Add relations > This endpoint is used to both create and update relations to the Outsmart account. Relations will be check for existing relations on the supplied \`debtor\_number\`\_.\_ When an existing debtor number is supplied, data on the existing relation will be updated.\ > \ > Each relation record can contain the following data:\ > \ > \| Parameter | Required | Description |\ > \| --- | --- | --- |\ > \| debtor\_number | Y | Unique id of the relation |\ > \| name | Y | Name of the relation |\ > \| contact | N | Name om the main contactperson of the relation |\ > \| phone\_number | N | Phone number |\ > \| email | N | Contact email address |\ > \| email\_workorder | N | Email address used when sending workorder to the customer |\ > \| street | Y | Relation address street name |\ > \| house\_number | N | Relation address house number |\ > \| postal\_code | Y | Relation address postal code |\ > \| city | Y | Relation address city |\ > \| country | N | Relation address country |\ > \| remark | N | Text field for any additional remarks on the relation |\ > \| latitude | N | Relation address latitude coordinate |\ > \| longitude | N | Relation address longitude coordinate |\ > \| external\_id | N | External id field, often used for storing id reference from external software |\ > \| debtor\_number\_invoice | N | |\ > \| kvk\_number | N | Chamber of commerce number |\ > \| vat\_number | N | VAT identification number |\ > \| debtor\_type | N | Indicates the relation type, for example: customer, lead etc |\ > \| language | N | Language selection, value indicated with a country code. Example 'nl' for Dutch |\ > \| accountmanager | N | |\ > \| mobile | N | Mobile phone number |\ > \| status | N | |\ > \| active | N | Indication whether the relation is active or not. Value 0 for incactive, 1 for active |\ > \| pgp\_code | N | |\ > \| source | N | |\ > \| lead\_phase | N | |\ > \| lead\_score | N | |\ > \| lead\_value | N | |\ > \| loss\_reason | N | |\ > \| lead\_value\_recurring | N | |\ > \| marketing\_opt\_out | N | |\ > \| discount\_sales | N | Discount percentage applied for this relation. Integer value |\ > \| created\_at | N | Datetime value indicating when the relation was created. Date format: YYYY-MM-DD HH:mm:ss |\ > \| modified\_at | N | Datetime value indicating the relation was last modified. Dat format: YYYY-MM-DD HH:mm:ss |\ > \| created\_by | N | Employee number of who created the relation |\ > \| modified\_by | N | Employee number of the last employee who modified the relation data |\ > \ > \*\*Freefields\*\*\ > \ > Additional freefields can be added to the relation data. Freefield data can be supplied bij adding a \`FreeFields\` JSON object with the relation. Freefields will only be added to the results when declared, use the \[Freefields]\() endpoint to see which fields have been set. Freefields are numbered 1-50. ```json {"openapi":"3.1.0","info":{"title":"OpenApi","version":"1.0.0"},"servers":[{"url":"{{api_url}}"},{"url":"https://www.werkbonapp.nl"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/relations/":{"post":{"summary":"Add relations","parameters":[{"name":"token","in":"query","schema":{"type":"string"}},{"name":"software_token","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Response_200","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"messages":{"type":"array"},"response":{"type":"integer"}}}}}}},"tags":["Relations"],"description":"This endpoint is used to both create and update relations to the Outsmart account. Relations will be check for existing relations on the supplied `debtor_number`_._ When an existing debtor number is supplied, data on the existing relation will be updated.\n\nEach relation record can contain the following data:\n\n| Parameter | Required | Description |\n| --- | --- | --- |\n| debtor_number | Y | Unique id of the relation |\n| name | Y | Name of the relation |\n| contact | N | Name om the main contactperson of the relation |\n| phone_number | N | Phone number |\n| email | N | Contact email address |\n| email_workorder | N | Email address used when sending workorder to the customer |\n| street | Y | Relation address street name |\n| house_number | N | Relation address house number |\n| postal_code | Y | Relation address postal code |\n| city | Y | Relation address city |\n| country | N | Relation address country |\n| remark | N | Text field for any additional remarks on the relation |\n| latitude | N | Relation address latitude coordinate |\n| longitude | N | Relation address longitude coordinate |\n| external_id | N | External id field, often used for storing id reference from external software |\n| debtor_number_invoice | N | |\n| kvk_number | N | Chamber of commerce number |\n| vat_number | N | VAT identification number |\n| debtor_type | N | Indicates the relation type, for example: customer, lead etc |\n| language | N | Language selection, value indicated with a country code. Example 'nl' for Dutch |\n| accountmanager | N | |\n| mobile | N | Mobile phone number |\n| status | N | |\n| active | N | Indication whether the relation is active or not. Value 0 for incactive, 1 for active |\n| pgp_code | N | |\n| source | N | |\n| lead_phase | N | |\n| lead_score | N | |\n| lead_value | N | |\n| loss_reason | N | |\n| lead_value_recurring | N | |\n| marketing_opt_out | N | |\n| discount_sales | N | Discount percentage applied for this relation. Integer value |\n| created_at | N | Datetime value indicating when the relation was created. Date format: YYYY-MM-DD HH:mm:ss |\n| modified_at | N | Datetime value indicating the relation was last modified. Dat format: YYYY-MM-DD HH:mm:ss |\n| created_by | N | Employee number of who created the relation |\n| modified_by | N | Employee number of the last employee who modified the relation data |\n\n**Freefields**\n\nAdditional freefields can be added to the relation data. Freefield data can be supplied bij adding a `FreeFields` JSON object with the relation. Freefields will only be added to the results when declared, use the [Freefields](https://documenter.getpostman.com/view/3100119/UVRDG5v7#a4d1b560-dd2b-4936-9ffe-80aee3514507) endpoint to see which fields have been set. Freefields are numbered 1-50."}}}} ``` --- # 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://knowledge.out-smart.com/openapi/relations.md?ask=&goal= ``` `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.