> For the complete documentation index, see [llms.txt](https://api-docs.helloaviary.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.helloaviary.ai/customer-data.md).
# Customer Data
Single- or multi-record customer ingestion. Served from `/singleAccountCallStart` and `/multipleAccountCallStart`.
## Account Call Start (Single or Multiple)
> Submits one customer for outbound calling. Returns once the\
> request has been accepted; calls are placed asynchronously.\
> \
> Two request shapes are accepted:\
> 1\. \*\*Single record\*\* — customer fields at the top level of the body.\
> 2\. \*\*Multiple records\*\* — multiple rows for the \*same\* contact in a\
> \`records\` array, so a single call can reference all of them.\
> \
> Optional \`allow\_multiple\_calls\_per\_day\` (boolean) may be set per\
> record or on the flat single-record body; omit or null to leave\
> any existing value unchanged.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Customer Data","description":"Single- or multi-record customer ingestion. Served from\n`/singleAccountCallStart` and `/multipleAccountCallStart`.\n"}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"SingleAccountCallStartRequest":{"oneOf":[{"type":"object","required":["clientName","useCaseName"],"properties":{"clientName":{"type":"string","description":"The name of the client"},"useCaseName":{"type":"string","description":"The name of the use case"},"allow_multiple_calls_per_day":{"$ref":"#/components/schemas/AllowMultipleCallsPerDayProperty"},"additionalProperties":{"type":"string","description":"Additional fields that match the column mappings for the use case"}},"description":"Single record format - customer fields are provided directly in the request body"},{"type":"object","required":["clientName","useCaseName","records"],"properties":{"clientName":{"type":"string","description":"The name of the client"},"useCaseName":{"type":"string","description":"The name of the use case"},"records":{"type":"array","minItems":1,"description":"Array of customer records for the same contact (one outbound call can reference all records); each object includes fields matching the column mappings for the use case","items":{"type":"object","properties":{"allow_multiple_calls_per_day":{"$ref":"#/components/schemas/AllowMultipleCallsPerDayProperty"}},"additionalProperties":{"type":"string"}}}},"description":"Multiple records format - customer records are provided in a \"records\" array (same contact, multiple data rows)"}]},"AllowMultipleCallsPerDayProperty":{"type":"boolean","description":"When true, relaxes same-day and related outbound frequency limits for this customer (multiple qualifying runs per day; a short cooldown may still apply).\nOmit the field or send JSON null: the existing database value is left unchanged for customers that already exist; for new customers the column defaults to false.\nWhen explicitly false, stores false.\n"},"SingleAccountCallStartResponse":{"type":"object","required":["message","callIDs","count"],"properties":{"message":{"type":"string"},"callIDs":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Array of unique identifiers for the call records that were created"},"count":{"type":"integer","description":"The number of call records created"},"callID":{"type":"integer","format":"int64","description":"The unique identifier of the call record (included for backward compatibility when only one record is processed)"}}},"ErrorResponse":{"type":"object","required":["message"],"description":"Legacy clientApi error shape. Distinct from `ErrorEnvelope` —\nthe legacy routes return a flat `{message, error?}` payload\nwithout a stable code or request_id.\n","properties":{"message":{"type":"string","description":"Error message"},"error":{"type":"string","description":"Detailed error information"}}}}},"paths":{"/singleAccountCallStart":{"post":{"summary":"Account Call Start (Single or Multiple)","description":"Submits one customer for outbound calling. Returns once the\nrequest has been accepted; calls are placed asynchronously.\n\nTwo request shapes are accepted:\n1. **Single record** — customer fields at the top level of the body.\n2. **Multiple records** — multiple rows for the *same* contact in a\n `records` array, so a single call can reference all of them.\n\nOptional `allow_multiple_calls_per_day` (boolean) may be set per\nrecord or on the flat single-record body; omit or null to leave\nany existing value unchanged.\n","operationId":"singleAccountCallStart","tags":["Customer Data"],"requestBody":{"description":"Customer payload (single-record or multi-record shape).","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAccountCallStartRequest"}}}},"responses":{"200":{"description":"Customer data processed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAccountCallStartResponse"}}}},"400":{"description":"Bad request - invalid body or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error (e.g. error processing customer data)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Multiple Account Call Start
> Submits one or more data records for the \*\*same single contact\*\*\
> in a \`records\` array. Use this when the contact has multiple\
> related rows (e.g. multiple accounts or line items) that should\
> be addressed on \*\*one\*\* outbound call — not for batching\
> unrelated people. Calls are placed asynchronously after the\
> request is accepted.\
> \
> Optional \`allow\_multiple\_calls\_per\_day\` (boolean) on each record\
> relaxes same-day frequency limits for that customer; omit or\
> null to leave any existing value unchanged.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"Customer Data","description":"Single- or multi-record customer ingestion. Served from\n`/singleAccountCallStart` and `/multipleAccountCallStart`.\n"}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"AllowMultipleCallsPerDayProperty":{"type":"boolean","description":"When true, relaxes same-day and related outbound frequency limits for this customer (multiple qualifying runs per day; a short cooldown may still apply).\nOmit the field or send JSON null: the existing database value is left unchanged for customers that already exist; for new customers the column defaults to false.\nWhen explicitly false, stores false.\n"},"SingleAccountCallStartResponse":{"type":"object","required":["message","callIDs","count"],"properties":{"message":{"type":"string"},"callIDs":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Array of unique identifiers for the call records that were created"},"count":{"type":"integer","description":"The number of call records created"},"callID":{"type":"integer","format":"int64","description":"The unique identifier of the call record (included for backward compatibility when only one record is processed)"}}},"ErrorResponse":{"type":"object","required":["message"],"description":"Legacy clientApi error shape. Distinct from `ErrorEnvelope` —\nthe legacy routes return a flat `{message, error?}` payload\nwithout a stable code or request_id.\n","properties":{"message":{"type":"string","description":"Error message"},"error":{"type":"string","description":"Detailed error information"}}}}},"paths":{"/multipleAccountCallStart":{"post":{"summary":"Multiple Account Call Start","description":"Submits one or more data records for the **same single contact**\nin a `records` array. Use this when the contact has multiple\nrelated rows (e.g. multiple accounts or line items) that should\nbe addressed on **one** outbound call — not for batching\nunrelated people. Calls are placed asynchronously after the\nrequest is accepted.\n\nOptional `allow_multiple_calls_per_day` (boolean) on each record\nrelaxes same-day frequency limits for that customer; omit or\nnull to leave any existing value unchanged.\n","operationId":"multipleAccountCallStart","tags":["Customer Data"],"requestBody":{"description":"Customer payload with a `records` array (1 or more records).","required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientName","useCaseName","records"],"properties":{"clientName":{"type":"string","description":"The name of the client"},"useCaseName":{"type":"string","description":"The name of the use case"},"records":{"type":"array","minItems":1,"description":"Array of data records for the same contact (1 or more rows); one call can reference all of them","items":{"type":"object","properties":{"allow_multiple_calls_per_day":{"$ref":"#/components/schemas/AllowMultipleCallsPerDayProperty"}},"additionalProperties":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Customer data processed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleAccountCallStartResponse"}}}},"400":{"description":"Bad request - invalid body or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Client or use case not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error (e.g. error processing customer data)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# 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://api-docs.helloaviary.ai/customer-data.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.