AgentPhone Registration API

openapi: 3.2.0
info:
  title: SMS Registration API
  description: A simple API to provision phone numbers and receive SMS
  version: 0.1.0
tags:
- name: Registration
paths:
  /v1/register/status:
    get:
      tags:
      - Registration
      summary: Get Registration Status
      description: 'Check the status of your A2P 10DLC registration.


        Registrations created with create_sub_account=true (the default) live on

        a sub-account; this resolves to it automatically when there''s exactly

        one, or honors the X-Sub-Account-Id header.'
      operationId: get_registration_status_v1_register_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignStatusResponse'
      security:
      - HTTPBearer: []
  /v1/register:
    get:
      tags:
      - Registration
      summary: Get Registration Details
      description: 'Retrieve the content of your submitted A2P 10DLC registration.


        Returns the brand identity and campaign content exactly as it was

        submitted (business info, description, use case, sample messages, opt-in

        consent flow, opt-in screenshot URL) so you can review what carriers are

        reviewing. Internal registry ids, vendor names, and processing state are

        never exposed; the coarse `stage` mirrors GET /v1/register/status. The

        EIN is returned as its last 4 digits only.


        Like the status endpoint, this resolves to a sub-account when the

        registration lives on one (the default for POST /v1/register) — either

        automatically when there''s exactly one, or via the X-Sub-Account-Id

        header.'
      operationId: get_registration_details_v1_register_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationDetailResponse'
      security:
      - HTTPBearer: []
    post:
      tags:
      - Registration
      summary: Register A2P
      description: 'Submit A2P 10DLC registration.


        Deducts the registration fee ($25 for sole_proprietor / standard_brand,

        $70 for high_volume) from the parent account''s credit balance, creates an

        optional sub-account, and sends a notification email.'
      operationId: register_a2p_v1_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
    patch:
      tags:
      - Registration
      summary: Update A2P Registration
      description: 'Update an existing A2P 10DLC registration.


        Send only the fields that changed — everything is optional. There is no

        fee. Changes are applied after review, and your registration keeps

        sending under its current approval while an update to an approved

        registration is reviewed.


        Registrations created with create_sub_account=true (the default) live on

        a sub-account; this resolves to it automatically when there''s exactly

        one, or honors the X-Sub-Account-Id header.'
      operationId: update_a2p_registration_v1_register_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationUpdateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationUpdateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RegistrationDetailResponse:
      properties:
        campaign_status:
          type: string
          title: Campaign Status
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
        issue:
          anyOf:
          - $ref: '#/components/schemas/RegistrationIssue'
          - type: 'null'
          description: 'Set when `stage` is `action_required`: the reason and what to change.'
        sub_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub Account Id
          description: Set when the registration lives on a sub-account of the calling account.
        brand:
          anyOf:
          - $ref: '#/components/schemas/RegistrationBrandDetail'
          - type: 'null'
        campaign:
          anyOf:
          - $ref: '#/components/schemas/RegistrationCampaignDetail'
          - type: 'null'
      type: object
      required:
      - campaign_status
      title: RegistrationDetailResponse
    UseCase:
      type: string
      enum:
      - account_notification
      - customer_care
      - delivery_notification
      - fraud_alert
      - higher_education
      - marketing
      - polling_voting
      - public_service_announcement
      - security_alert
      - two_factor_authentication
      title: UseCase
    RegistrationRequest:
      properties:
        registration_type:
          type: string
          enum:
          - sole_proprietor
          - standard_brand
          - high_volume
          title: Registration Type
          description: '''sole_proprietor'' ($25, no EIN, 1 number), ''standard_brand'' ($25, EIN, low volume), or ''high_volume'' ($70, EIN + external brand vetting for the highest carrier limits)'
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
        email:
          type: string
          title: Email
        phone_number:
          type: string
          title: Phone Number
          description: E.164 format, e.g. +15551234567
        business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Name
          description: Legal/registered business name. Required for standard_brand and high_volume.
        brand_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Name
          description: Public-facing brand name if different from business_name.
        organization_type:
          anyOf:
          - $ref: '#/components/schemas/OrganizationType'
          - type: 'null'
          description: Required for standard_brand and high_volume.
        contact_title:
          anyOf:
          - $ref: '#/components/schemas/ContactTitle'
          - type: 'null'
          description: Your role. Required for standard_brand and high_volume.
        contact_title_other:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Title Other
          description: Custom title when contact_title is 'other'.
        ein:
          anyOf:
          - type: string
          - type: 'null'
          title: Ein
          description: EIN / Tax ID. Required for standard_brand and high_volume.
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Website Url
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
          description: e.g. technology, real_estate, retail, healthcare
        business_regions:
          items:
            type: string
          type: array
          title: Business Regions
          default:
          - usa_and_canada
        street_address:
          type: string
          title: Street Address
        street_address_2:
          anyOf:
          - type: string
          - type: 'null'
          title: Street Address 2
        city:
          type: string
          title: City
        state:
          type: string
          title: State
        zip_code:
          type: string
          title: Zip Code
        country:
          type: string
          title: Country
          default: US
        planned_numbers:
          type: integer
          title: Planned Numbers
          description: Number of phone numbers you plan to use
          default: 1
        description:
          type: string
          maxLength: 4096
          minLength: 40
          title: Description
          description: What your business does, who you message, and what types of messages you send. Min 40 chars.
        use_cases:
          items:
            $ref: '#/components/schemas/UseCase'
          type: array
          maxItems: 5
          minItems: 1
          title: Use Cases
          description: 1-5 specific use cases for your SMS campaign.
        volume:
          allOf:
          - $ref: '#/components/schemas/Volume'
          description: Expected message volume.
          default: low
        message_samples:
          items:
            type: string
          type: array
          maxItems: 5
          minItems: 2
          title: Message Samples
          description: 2-5 example messages. Each must be 20-1024 chars and include your brand name.
        consent_flow:
          type: string
          maxLength: 4096
          minLength: 40
          title: Consent Flow
          description: How users opt in to receive messages. Min 40 chars.
        privacy_policy_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Privacy Policy Url
          description: Required for standard_brand and high_volume. Optional for sole_proprietor.
        terms_of_service_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Terms Of Service Url
          description: Required for standard_brand and high_volume. Optional for sole_proprietor.
        opt_in_image_url:
          type: string
          title: Opt In Image Url
          description: Publicly accessible URL to a screenshot of your opt-in flow (PNG, JPG, WEBP, or GIF, max 2MB)
        includes:
          items:
            $ref: '#/components/schemas/CampaignInclude'
          type: array
          title: Includes
          description: Content types included in messages.
          default: []
        link_sample:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Link Sample
          description: Example URL if messages contain links.
        create_sub_account:
          type: boolean
          title: Create Sub Account
          description: Create a dedicated sub-account for this campaign. Set false to register on your main account.
          default: true
      type: object
      required:
      - registration_type
      - first_name
      - last_name
      - email
      - phone_number
      - street_address
      - city
      - state
      - zip_code
      - description
      - use_cases
      - message_samples
      - consent_flow
      - opt_in_image_url
      title: RegistrationRequest
    Volume:
      type: string
      enum:
      - low
      - high
      title: Volume
    CampaignInclude:
      type: string
      enum:
      - links
      - phone_numbers
      - age_gated
      - direct_lending
      title: CampaignInclude
    RegistrationResponse:
      properties:
        ok:
          type: boolean
          title: Ok
        message:
          type: string
          title: Message
        campaign_status:
          type: string
          title: Campaign Status
        sub_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub Account Id
        fee_cents:
          type: integer
          title: Fee Cents
      type: object
      required:
      - ok
      - message
      - campaign_status
      - fee_cents
      title: RegistrationResponse
    RegistrationUpdateRequest:
      properties:
        first_name:
          anyOf:
          - type: string
          - type: 'null'
          title: First Name
          description: Contact first name.
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
          description: Contact last name.
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: Contact email address.
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
          description: E.164 format, e.g. +15551234567
        business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Name
          description: Legal/registered business name.
        brand_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Name
          description: Public-facing brand name if different from business_name.
        organization_type:
          anyOf:
          - $ref: '#/components/schemas/OrganizationType'
          - type: 'null'
          description: Organization type.
        contact_title:
          anyOf:
          - $ref: '#/components/schemas/ContactTitle'
          - type: 'null'
          description: Your role.
        contact_title_other:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Title Other
          description: Custom title when contact_title is 'other'.
        ein:
          anyOf:
          - type: string
          - type: 'null'
          title: Ein
          description: EIN / Tax ID.
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Website Url
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
          description: e.g. technology, real_estate, retail, healthcare
        business_regions:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Business Regions
          description: e.g. ['usa_and_canada']
        street_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Street Address
          description: Street address line 1.
        street_address_2:
          anyOf:
          - type: string
          - type: 'null'
          title: Street Address 2
          description: Street address line 2 (suite, unit, etc.).
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: City.
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          description: State/region code.
        zip_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Zip Code
          description: Postal/ZIP code.
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: Country code, e.g. US.
        description:
          anyOf:
          - type: string
            maxLength: 4096
            minLength: 40
          - type: 'null'
          title: Description
          description: What your business does, who you message, and what types of messages you send. Min 40 chars.
        use_cases:
          anyOf:
          - items:
              $ref: '#/components/schemas/UseCase'
            type: array
            maxItems: 5
            minItems: 1
          - type: 'null'
          title: Use Cases
          description: 1-5 specific use cases for your SMS campaign.
        volume:
          anyOf:
          - $ref: '#/components/schemas/Volume'
          - type: 'null'
          description: Expected message volume.
        message_samples:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 5
            minItems: 2
          - type: 'null'
          title: Message Samples
          description: 2-5 example messages. Each must be 20-1024 chars and include your brand name.
        consent_flow:
          anyOf:
          - type: string
            maxLength: 4096
            minLength: 40
          - type: 'null'
          title: Consent Flow
          description: How users opt in to receive messages. Min 40 chars.
        privacy_policy_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Privacy Policy Url
        terms_of_service_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Terms Of Service Url
        opt_in_image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Opt In Image Url
          description: Publicly accessible URL to a screenshot of your opt-in flow (PNG, JPG, WEBP, or GIF, max 2MB)
        includes:
          anyOf:
          - items:
              $ref: '#/components/schemas/CampaignInclude'
            type: array
          - type: 'null'
          title: Includes
          description: Content types included in messages.
        link_sample:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Link Sample
          description: Example URL if messages contain links.
      type: object
      title: RegistrationUpdateRequest
      description: 'Partial update to an existing registration. Every field is optional;

        provide only what changed. No fee — updates go through review before

        taking effect.'
    OrganizationType:
      type: string
      enum:
      - sole_proprietor
      - private_corporation
      - public_corporation
      - llc
      - partnership
      - non_profit
      - co_op
      - government
      title: OrganizationType
    ContactTitle:
      type: string
      enum:
      - ceo
      - cfo
      - cto
      - coo
      - vp
      - gm
      - director
      - other
      title: ContactTitle
    CampaignStatusResponse:
      properties:
        campaign_status:
          type: string
          title: Campaign Status
        message:
          type: string
          title: Message
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
        issue:
          anyOf:
          - $ref: '#/components/schemas/RegistrationIssue'
          - type: 'null'
          description: 'Set when `stage` is `action_required`: the reason and what to change. For a registration under review, resubmitting with PATCH /v1/register clears it. A registration that failed carrier review (`campaign_status` back to `none`) is resubmitted with POST /v1/register; a suspended one needs support.'
        sub_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub Account Id
          description: Set when the registration lives on a sub-account of the calling account (the default for POST /v1/register). Pass it as the X-Sub-Account-Id header to address that sub-account directly.
      type: object
      required:
      - campaign_status
      - message
      title: CampaignStatusResponse
    RegistrationBrandDetail:
      properties:
        business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Name
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Website Url
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
        entity_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Type
        ein:
          anyOf:
          - type: string
          - type: 'null'
          title: Ein
          description: The EIN / Tax ID as submitted.
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone
        contact_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Name
        street_address:
          anyOf:
          - type: string
          - type: 'null'
          title: Street Address
        street_address_2:
          anyOf:
          - type: string
          - type: 'null'
          title: Street Address 2
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        zip_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Zip Code
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
      type: object
      title: RegistrationBrandDetail
    RegistrationCampaignDetail:
      properties:
        use_case:
          anyOf:
          - type: string
          - type: 'null'
          title: Use Case
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        message_samples:
          items:
            type: string
          type: array
          title: Message Samples
          default: []
        consent_flow:
          anyOf:
          - type: string
          - type: 'null'
          title: Consent Flow
        opt_in_image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Opt In Image Url
        includes:
          items:
            type: string
          type: array
          title: Includes
          description: Content types detected in the submitted samples, e.g. 'links', 'phone_numbers'.
          default: []
      type: object
      title: RegistrationCampaignDetail
    RegistrationIssue:
      properties:
        code:
          type: string
          title: Code
          description: Why the registration needs attention. One of `brand_name_ein_mismatch`, `opt_in_evidence_required`, `campaign_rejected`, `campaign_suspended`, `other`.
        message:
          type: string
          title: Message
          description: What to fix, in plain language.
        since:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
          description: When the issue was raised (ISO 8601).
      type: object
      required:
      - code
      - message
      title: RegistrationIssue
    RegistrationUpdateResponse:
      properties:
        ok:
          type: boolean
          title: Ok
        message:
          type: string
          title: Message
        campaign_status:
          type: string
          title: Campaign Status
        updated_fields:
          items:
            type: string
          type: array
          title: Updated Fields
        sub_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub Account Id
          description: Set when the update was applied to a registration on a sub-account of the calling account (the default for POST /v1/register).
      type: object
      required:
      - ok
      - message
      - campaign_status
      - updated_fields
      title: RegistrationUpdateResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer