answeringservicecare-com Batch API

openapi: 3.2.0
info:
  title: Answering Service Care Public Batch API
  version: 1.0.0
  summary: 'Read-only facts about Answering Service Care: company details, services, pricing, and site search.'
  description: 'Answering Service Care (ASC) is a 24/7 US-based answering service with live and AI receptionists. This public API needs no authentication and is safe to call from agents: every operation is a read-only GET. Errors are JSON objects with `code`, `message`, `hint`, and `documentation_url`.


    **Rate limits.** 60 requests per minute per client. Every response carries `RateLimit-Policy` and `RateLimit` headers (IETF draft-ietf-httpapi-ratelimit-headers) plus `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; over the limit you get a `429` with `Retry-After`.


    **Versioning and deprecation.** The major version is in the path (`/api/v1`). Changes within v1 are additive only: new endpoints, fields, and optional parameters. A breaking change ships as a new version (`/api/v2`), and v1 keeps working for at least 12 months after that. During that time v1 responses carry `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers and a `Link` with `rel="deprecation"` pointing to the migration notice at https://answeringservicecare.com/developers/.


    **Pagination.** `/search` is cursor-paginated: pass a response''s `nextCursor` as `cursor` to get the next page; `nextCursor` is null on the last page.


    **Batch and async jobs.** `POST /batch` runs up to 10 of the GET operations in one request; each one counts toward the rate limit. Send `Prefer: respond-async` to get `202 Accepted` with a `Location` job URL instead, then `GET` that URL for the results (jobs expire after 24 hours).


    **Idempotency.** `POST /batch` accepts an `Idempotency-Key` header and echoes it back. Every operation in a batch is a read, so retrying with the same key never repeats a side effect.


    **Sandbox.** `https://answeringservicecare.com/api/sandbox/v1` serves every operation, including batches, from fixed sample data with `"sandbox": true`, for testing clients against stable responses. It shares the rate limit.


    Existing ASC customers also have a separate, authenticated REST API for messages, call recordings, and to-dos; see https://answeringservicecare.com/docs/api-reference/.'
  contact:
    name: Answering Service Care
    url: https://answeringservicecare.com/contact-us/
    email: sales@answeringservicecare.com
  termsOfService: https://answeringservicecare.com/terms-and-conditions/
servers:
- url: https://answeringservicecare.com/api/v1
  description: Production
- url: https://answeringservicecare.com/api/sandbox/v1
  description: 'Sandbox: fixed sample data for testing, not real plans or prices'
security: []
tags:
- name: Batch
  description: Several operations in one request, optionally as an async job.
paths:
  /batch:
    post:
      operationId: runBatch
      tags:
      - Batch
      summary: Run several operations in one request
      description: 'Runs up to 10 GET operations (company, services, pricing, search) and returns each result with its own status. Every operation counts toward the rate limit. With `Prefer: respond-async` the batch is accepted as a job (202) to fetch from the `Location` URL. All operations are reads, so the request is safe to retry; send an `Idempotency-Key` to correlate retries.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Client-chosen unique key (e.g. a UUID) for this logical request, reused only on retries. Echoed in the response.
        schema:
          type: string
          minLength: 1
          maxLength: 255
      - name: Prefer
        in: header
        required: false
        description: Send `respond-async` to run the batch as a job and get 202 Accepted with a Location to poll.
        schema:
          type: string
          enum:
          - respond-async
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Each operation's result, in order
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '202':
          description: Accepted as a job; GET the Location URL for the results
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Location:
              description: Job URL to poll.
              schema:
                type: string
                format: uri
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Invalid batch or Idempotency-Key (codes rest_invalid_param, rest_invalid_json, invalid_idempotency_key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Batch too large to run as an async job (code batch_too_large)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (code rate_limited); wait for Retry-After seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /batch/jobs/{jobId}:
    get:
      operationId: getBatchJob
      tags:
      - Batch
      summary: Get an async batch job's results
      description: Returns the job's status and each operation's result. Job IDs come from the Location header of a 202 response and expire after 24 hours.
      parameters:
      - name: jobId
        in: path
        required: true
        description: The jobId from the 202 response.
        schema:
          type: string
      responses:
        '200':
          description: Job status and results
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResult'
        '404':
          description: No such job, or it has expired (code job_not_found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (code rate_limited); wait for Retry-After seconds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BatchResponse:
      type: object
      required:
      - responses
      properties:
        responses:
          type: array
          items:
            $ref: '#/components/schemas/BatchResult'
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code, e.g. rest_no_route.
        message:
          type: string
          description: Human-readable explanation.
        hint:
          type: string
          description: What to change to make the request succeed.
        documentation_url:
          type: string
          format: uri
        data:
          type: object
          properties:
            status:
              type: integer
    JobAccepted:
      type: object
      required:
      - jobId
      - status
      - statusUrl
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
          - accepted
        statusUrl:
          type: string
          format: uri
        requests:
          type: integer
        expiresAt:
          type: string
          format: date-time
    BatchRequest:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: object
            required:
            - path
            additionalProperties: false
            properties:
              id:
                type: string
                maxLength: 64
                description: Your label for this operation, echoed in its result. Defaults to its position (1, 2, ...).
              method:
                type: string
                enum:
                - GET
              path:
                type: string
                enum:
                - /company
                - /services
                - /pricing
                - /search
              query:
                type: object
                description: Query parameters for the operation; list values comma-separated.
                additionalProperties:
                  type:
                  - string
                  - integer
    JobResult:
      type: object
      required:
      - jobId
      - status
      - responses
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
          - completed
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        responses:
          type: array
          items:
            $ref: '#/components/schemas/BatchResult'
    BatchResult:
      type: object
      required:
      - id
      - status
      - body
      properties:
        id:
          type: string
        status:
          type: integer
          description: HTTP status of this operation.
        body:
          description: The operation's JSON response or error.
  headers:
    RateLimit:
      description: Remaining quota and seconds until it resets, e.g. `"default";r=59;t=42`.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimit-Policy:
      description: Quota policy, e.g. `"default";q=60;w=60` (60 requests per 60 seconds).
      schema:
        type: string
    Idempotency-Key:
      description: The Idempotency-Key sent with the request, echoed back.
      schema:
        type: string
externalDocs:
  description: Developer overview
  url: https://answeringservicecare.com/developers/