> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dialbird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a contact

> Creates a contact in the caller's business. At least one of
`primary_phone` or `primary_email` is required. Match-and-merge,
validation, and analytics behave identically to the in-app path.




## OpenAPI

````yaml /openapi.yaml post /contacts
openapi: 3.1.0
info:
  title: Dialbird Public API
  version: 1.0.0
  description: >
    The Dialbird Public API is a versioned, machine-to-machine REST surface for

    building automations on top of Dialbird (Zapier, n8n, Make, custom scripts).


    ## Authentication


    All endpoints except `GET /health` require an OAuth 2.0 bearer access token

    obtained via the Authorization Code flow against Dialbird's OIDC provider.

    The token is a signed JWT with `aud: "public-api"`; the API verifies it

    against the issuer's JWKS. Send it on every request:


    ```

    Authorization: Bearer <access_token>

    ```


    Access tokens must **never** be passed as a `?access_token=` query parameter
    —

    requests that do are rejected with `401 invalid_token`.


    ## Request & response conventions


    - All request and response bodies are JSON (`application/json`).

    - Field names are `snake_case`.

    - Every response carries an `X-Request-Id` header. Include it when
    contacting
      support. Clients may supply their own via the `X-Request-Id` request header
      (`^[A-Za-z0-9_-]{1,64}$`); otherwise the API generates one.
    - Phone numbers are always E.164 (e.g. `+15551234567`).


    ## Idempotency


    Write endpoints (`POST /contacts`, `POST /messages`) accept an optional

    `Idempotency-Key` header (≤255 chars). Retrying a request with the same key

    and identical body replays the original response without re-running the

    operation. Reusing a key with a *different* body returns `409

    idempotency_key_reused`; a retry while the first request is still in flight

    returns `409` with code `idempotency_in_progress`. Keys are retained for
    24h.


    ## Rate limiting


    Authenticated requests are limited per `(business, oauth_client)`; anonymous

    requests (only `GET /health`) are limited per IP. Every response includes:


    - `X-RateLimit-Limit` — requests allowed in the current window

    - `X-RateLimit-Remaining` — requests left in the window

    - `X-RateLimit-Reset` — unix epoch seconds when the window resets


    A `429 rate_limited` response additionally carries a `Retry-After` header

    (seconds).


    ## Errors


    Errors share one envelope:


    ```json

    { "error": { "code": "not_found", "message": "…", "field": "to",
    "request_id": "req_…" } }

    ```


    `field` is present only for validation errors that map to a specific input.
  contact:
    name: Dialbird Support
    email: team@usechalkboard.com
servers:
  - url: '{origin}/api/v1'
    description: Dialbird Public API base URL
    variables:
      origin:
        default: https://app-staging.dialbird.io
        description: The Dialbird deployment origin (matches the OIDC issuer host).
security:
  - OAuth2: []
tags:
  - name: System
    description: Unauthenticated health checks.
  - name: Identity
    description: The authenticated principal.
  - name: Contacts
    description: Create and update contacts.
  - name: Messages
    description: Send SMS messages.
  - name: Webhooks
    description: Manage REST-Hook webhook subscriptions.
paths:
  /contacts:
    post:
      tags:
        - Contacts
      summary: Create a contact
      description: |
        Creates a contact in the caller's business. At least one of
        `primary_phone` or `primary_email` is required. Match-and-merge,
        validation, and analytics behave identically to the in-app path.
      operationId: createContact
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactWrite'
            examples:
              minimal:
                value:
                  primary_phone: '+15551234567'
              full:
                value:
                  first_name: Ada
                  last_name: Lovelace
                  primary_phone: '+15551234567'
                  primary_email: ada@example.com
                  notes: VIP customer
      responses:
        '201':
          description: Contact created.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - OAuth2:
            - api:contacts:write
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Client-generated key (≤255 chars) to make a write request safely
        retriable.
      schema:
        type: string
        maxLength: 255
  schemas:
    ContactWrite:
      type: object
      description: At least one of `primary_phone` / `primary_email` is required on create.
      properties:
        first_name:
          type: string
        last_name:
          type: string
        primary_phone:
          type: string
          description: E.164.
          example: '+15551234567'
        primary_email:
          type: string
          format: email
        notes:
          type: string
    Contact:
      type: object
      properties:
        id:
          type: string
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        primary_phone:
          type:
            - string
            - 'null'
        primary_email:
          type:
            - string
            - 'null'
        notes:
          type:
            - string
            - 'null'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
            field:
              type: string
              description: >-
                Present only for validation errors tied to a specific input
                field.
            request_id:
              type: string
    ErrorCode:
      type: string
      enum:
        - validation_error
        - invalid_phone_number
        - invalid_event_type
        - missing_token
        - invalid_token
        - expired_token
        - insufficient_scope
        - forbidden
        - business_suspended
        - not_found
        - conflict
        - idempotency_key_reused
        - idempotency_in_progress
        - gone
        - unprocessable_entity
        - rate_limited
        - internal_error
  headers:
    RequestId:
      description: Echoes the request id (client-supplied or generated).
      schema:
        type: string
    WWWAuthenticate:
      description: Bearer challenge.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix epoch seconds when the window resets.
      schema:
        type: integer
  responses:
    ValidationError:
      description: The request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, invalid, or expired token.
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WWWAuthenticate'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Token lacks the required scope, or the business is suspended / not
        associated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyConflict:
      description: |
        The `Idempotency-Key` was reused with a different body
        (`idempotency_key_reused`) or a prior request with the same key is still
        in flight (`idempotency_in_progress`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        Authorization Code flow against Dialbird's OIDC provider. The issued
        access token is a JWT with `aud: "public-api"`, verified against the
        issuer JWKS.
      flows:
        authorizationCode:
          authorizationUrl: https://app-staging.dialbird.io/oidc/auth
          tokenUrl: https://app-staging.dialbird.io/oidc/token
          refreshUrl: https://app-staging.dialbird.io/oidc/token
          scopes:
            api:me: Read the authenticated business, user, and granted scopes.
            api:contacts:read: Read contacts.
            api:contacts:write: Create and update contacts.
            api:messages:read: Read messages.
            api:messages:write: Send messages.
            api:calls:read: Read calls.
            api:webhooks: Manage webhook subscriptions.

````