> ## Documentation Index > Fetch the complete documentation index at: https://docs.getoliver.com/llms.txt > Use this file to discover all available pages before exploring further. # Trigger AI Outbound Contact > Trigger an AI outbound contact flow (SMS today) for a single client. Intake is synchronous — Oliver validates the request, resolves the target client, and runs suppression checks before responding. The actual outreach is dispatched asynchronously; the final outcome is delivered to your `callback_url` webhook, if provided. A suppressed request is **not** an error: it returns `200 OK` with `status: "suppressed"` and a `suppression_reason`. Only malformed or unresolvable input returns a `400`. Provide at least one of `client_id` or `contact_number` to identify the target. Set `partner_request_id` to make the call idempotent — re-submitting the same value returns the existing request instead of creating a new one. ## OpenAPI ````yaml POST /services/core/open_api/v1/ai_outbound/requests openapi: 3.1.0 info: title: Oliver Partner API description: API for partners to interact with Oliver license: name: MIT version: 1.0.0 servers: - url: https://partner-api.getoliver.com security: - bearerAuth: [] paths: /services/core/open_api/v1/ai_outbound/requests: post: summary: Trigger an AI outbound contact description: >- Trigger an AI outbound contact flow (SMS today) for a single client. Intake is synchronous — Oliver validates the request, resolves the target client, and runs suppression checks before responding. The actual outreach is dispatched asynchronously; the final outcome is delivered to your `callback_url` webhook, if provided. A suppressed request is **not** an error: it returns `200 OK` with `status: "suppressed"` and a `suppression_reason`. Only malformed or unresolvable input returns a `400`. Provide at least one of `client_id` or `contact_number` to identify the target. Set `partner_request_id` to make the call idempotent — re-submitting the same value returns the existing request instead of creating a new one. parameters: - name: X-Client-Id in: header description: The location id of the practice required: true schema: type: string requestBody: description: The AI outbound contact to trigger required: true content: application/json: schema: $ref: '#/components/schemas/CreateAiOutboundRequest' responses: '200': description: >- Request suppressed, or an existing request returned for a duplicate `partner_request_id` content: application/json: schema: type: object required: - success - data properties: success: type: boolean data: $ref: '#/components/schemas/AiOutboundRequest' message: type: string nullable: true '201': description: Request accepted and queued for dispatch content: application/json: schema: type: object required: - success - data properties: success: type: boolean data: $ref: '#/components/schemas/AiOutboundRequest' message: type: string nullable: true '400': description: >- Bad Request — invalid channel/purpose, missing target, or the client could not be resolved content: application/json: schema: $ref: '#/components/schemas/GeneralError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/GeneralError' '429': description: >- Too Many Requests — the per-practice rate limit (120/minute) was exceeded content: application/json: schema: $ref: '#/components/schemas/GeneralError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/GeneralError' components: schemas: CreateAiOutboundRequest: type: object required: - purpose - contact_number description: >- Provide `contact_number` to identify the target client. `client_id` may also be supplied to resolve the client directly. properties: purpose: type: string enum: - scheduling - callback_followup - refill - general description: The reason for the outreach. Required. channel: type: string enum: - sms - voice default: sms description: The outreach channel. Defaults to `sms`. client_id: type: string description: >- Oliver's identifier for the target client. Optional; resolves the client directly. contact_number: type: string description: The client's phone number in E.164 or local format. Required. client_name: type: string description: >- Client name used to disambiguate when a `contact_number` is shared across multiple client records (e.g. a household). patient_id: type: string description: >- Oliver's identifier for the patient the outreach concerns, if applicable. patient_name: type: string description: Patient name, used to match a patient within the resolved client. context: type: string description: >- Free-text context that guides the AI opener (e.g. "overdue for annual wellness exam"). initial_message_script: type: string description: >- The exact opening message for the AI to send. If provided, Oliver uses it verbatim; otherwise Oliver generates an opener based on the `purpose`. partner_request_id: type: string description: >- Your idempotency key. Re-submitting the same value returns the existing request instead of creating a new one. callback_url: type: string format: uri description: >- HTTPS URL that receives the outcome webhook when the request reaches a terminal status. Must begin with `https://`. AiOutboundRequest: type: object properties: id: type: string description: Oliver's unique identifier for the request. partner_request_id: type: string nullable: true description: The idempotency key you supplied, if any. channel: type: string enum: - sms - voice description: The outreach channel. `sms` is currently supported. purpose: type: string enum: - scheduling - callback_followup - refill - general description: The reason for the outreach, which shapes the AI opener. status: type: string enum: - received - queued - in_progress - completed - suppressed - failed description: >- Lifecycle status. `queued` → `in_progress` → one of the terminal states `completed`, `suppressed`, `failed`. outcome: type: string nullable: true enum: - booked - opted_out - no_response - undeliverable description: Set once a `completed` request reaches a resolution. suppression_reason: type: string nullable: true description: >- Why the request was suppressed, when `status` is `suppressed`. E.g. `recent_contact`, `active_conversation`, `sms_opted_out`, `voice_not_supported`. error_message: type: string nullable: true description: Failure detail, when `status` is `failed`. client_id: type: string nullable: true description: Oliver's identifier for the resolved client. patient_id: type: string nullable: true description: >- Oliver's identifier for the resolved patient, if one was provided or matched. contact_number: type: string nullable: true description: The contact number as you submitted it. context: type: string nullable: true description: The free-text context you supplied to guide the outreach. contacted_at: type: string format: date-time nullable: true description: When the first outbound message was sent, in ISO 8601 format. completed_at: type: string format: date-time nullable: true description: When the request reached a terminal status, in ISO 8601 format. created_at: type: string format: date-time description: When the request was created, in ISO 8601 format. GeneralError: type: object required: - success - message properties: success: type: boolean message: type: string data: type: object securitySchemes: bearerAuth: type: http scheme: bearer ````