Roark Phone Number API

openapi: 3.2.0
info:
  title: Roark Analytics Phone Number API
  description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
  version: 1.0.0
servers:
- description: Production
  url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Phone Number
paths:
  /v1/phone-number:
    get:
      responses:
        '200':
          description: The phone numbers the project owns
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumberResponse'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Phone-number
      tags:
      - Phone Number
      summary: List phone numbers
      description: Returns the phone numbers the project owns, oldest first, with the agent each is assigned to.
      parameters:
      - in: query
        name: agentId
        schema:
          type: string
          format: uuid
          description: Only the numbers assigned to this agent
    post:
      responses:
        '201':
          description: The purchased phone number
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PhoneNumberResponse'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Insufficient credit
              example:
                type: payment_required
                code: insufficient_credits
                message: Not enough credit to start this work. Add credit and try again.
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Conflict error
              example:
                type: conflict
                code: resource_in_use
                message: The resource is in use and cannot be deleted
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: postV1Phone-number
      tags:
      - Phone Number
      summary: Buy a phone number
      description: 'Buys a number from the carrier for this project: the one named by e164, or one Roark picks to match autoPick (trying the next match if the carrier has just sold one). Free inside the plan allowance; past it, the first month of rent is charged now and monthly after that.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePhoneNumberInput'
  /v1/phone-number/available:
    get:
      responses:
        '200':
          description: Numbers available to buy
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AvailablePhoneNumberResponse'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Phone-numberAvailable
      tags:
      - Phone Number
      summary: Search available phone numbers
      description: Returns US or Canadian numbers the carrier has for sale, local or toll-free, narrowed by area code or by digits the number must contain. When an area code has no numbers, nearby ones are returned flagged bestEffort; an empty list means nothing matched. Buy one with POST /v1/phone-number, or let Roark pick with autoPick.
      parameters:
      - in: query
        name: country
        schema:
          type: string
          enum:
          - US
          - CA
          description: 'ISO 3166-1 alpha-2 country of the number: US or CA'
          example: US
          default: US
      - in: query
        name: numberType
        schema:
          type: string
          enum:
          - LOCAL
          - TOLL_FREE
          description: LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool
          example: LOCAL
          default: LOCAL
      - in: query
        name: areaCode
        schema:
          type: string
          pattern: ^\d{3}$
          description: Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.
          example: '415'
      - in: query
        name: contains
        schema:
          type: string
          pattern: ^[0-9A-Za-z*]{1,7}$
          description: Digits or letters the number must contain (1 to 7, * matches any digit)
          example: '555'
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: 'Maximum number of results (default: 20, max: 100)'
  /v1/phone-number/allowance:
    get:
      responses:
        '200':
          description: The phone number allowance
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PhoneNumberAllowanceResponse'
                required:
                - data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Phone-numberAllowance
      tags:
      - Phone Number
      summary: Get the phone number allowance
      description: Returns how many numbers the organization gets for free, how many it holds, what a paid number costs a month, and whether a purchase would be admitted right now.
  /v1/phone-number/{phoneNumberId}:
    put:
      responses:
        '200':
          description: The updated phone number
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PhoneNumberResponse'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: putV1Phone-numberByPhoneNumberId
      tags:
      - Phone Number
      summary: Update a phone number
      description: Relabels a number or changes which agent it is assigned to. A field left out is untouched; null clears it.
      parameters:
      - in: path
        name: phoneNumberId
        schema:
          type: string
          format: uuid
          description: Phone number ID
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePhoneNumberInput'
    delete:
      responses:
        '200':
          description: The number was released
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ReleasePhoneNumberResponse'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: deleteV1Phone-numberByPhoneNumberId
      tags:
      - Phone Number
      summary: Release a phone number
      description: 'Gives the number back to the carrier. This cannot be undone: rent stops today and nothing is refunded.'
      parameters:
      - in: path
        name: phoneNumberId
        schema:
          type: string
          format: uuid
          description: Phone number ID
        required: true
components:
  schemas:
    UpdatePhoneNumberInput:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 80
          description: New label; null clears it, omit to leave it alone
        agentId:
          type:
          - string
          - 'null'
          format: uuid
          description: Agent to assign the number to; null unassigns, omit to leave it alone
      description: Input for relabelling or reassigning a phone number
    PhoneNumberAllowanceResponse:
      type: object
      properties:
        plan:
          type: string
          enum:
          - PAYG
          - TEAM
          - ENTERPRISE
          description: The billing plan the allowance comes from
        freeLimit:
          type: integer
          description: Numbers included at no charge
        used:
          type: integer
          description: Numbers the organization holds right now
        paidCount:
          type: integer
          description: How many of those sit outside the free allowance
        monthlyRentMicros:
          type: integer
          description: What one paid number costs a month, in micro-dollars
        nextIsFree:
          type: boolean
          description: Whether the next number would be free
        canPurchase:
          type: boolean
          description: Whether a purchase would be admitted right now
        blockedReason:
          type:
          - string
          - 'null'
          enum:
          - PAYMENT_METHOD_REQUIRED
          - INSUFFICIENT_CREDITS
          - SPEND_CAP_REACHED
          - PLAN_LIMIT_REACHED
          description: Why a purchase would be refused; null when canPurchase is true
        isOverridden:
          type: boolean
          description: True when the free allowance comes from a per-organization override
      required:
      - plan
      - freeLimit
      - used
      - paidCount
      - monthlyRentMicros
      - nextIsFree
      - canPurchase
      - blockedReason
      - isOverridden
      description: How many numbers the organization gets for free and whether it may buy the next one
    PhoneNumberAutoPickInput:
      type: object
      properties:
        country:
          type: string
          enum:
          - US
          - CA
          description: 'ISO 3166-1 alpha-2 country of the number: US or CA'
          example: US
          default: US
        numberType:
          type: string
          enum:
          - LOCAL
          - TOLL_FREE
          description: LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool
          example: LOCAL
          default: LOCAL
        areaCode:
          type: string
          pattern: ^\d{3}$
          description: Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.
          example: '415'
        contains:
          type: string
          pattern: ^[0-9A-Za-z*]{1,7}$
          description: Digits or letters the number must contain (1 to 7, * matches any digit)
          example: '555'
      description: What the number Roark picks should look like. Roark buys the first matching number the carrier will sell, preferring the area code and falling back to a nearby one.
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - validation
          - authentication
          - forbidden
          - not_found
          - conflict
          - payment_required
          - rate_limit
          - internal
          description: The error type category
          examples:
          - validation
          - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
          - invalid_parameter
          - missing_required_field
          - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
          - The request was invalid
          - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
          - email
          - user_id
        details:
          description: Additional error context information
      required:
      - type
      - code
      - message
    CreatePhoneNumberInput:
      type: object
      properties:
        e164:
          type: string
          pattern: ^\+[1-9]\d{1,14}$
          description: The number to buy, in E.164 format, from a search result. Give this or autoPick.
          example: '+14155550123'
        autoPick:
          $ref: '#/components/schemas/PhoneNumberAutoPickInput'
          description: Let Roark pick a matching number instead of naming one. Give this or e164.
        country:
          type: string
          enum:
          - US
          - CA
          description: 'The country of the number given by e164 (default: US). An auto-picked number uses autoPick.country.'
          example: US
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: A label for the number
        agentId:
          type: string
          format: uuid
          description: The agent to assign the number to
        expectFree:
          type: boolean
          description: Whether you expect this number to be free (from the allowance). The purchase is refused with 409 if that has changed since you checked.
        expectMonthlyRentMicros:
          type: integer
          minimum: 0
          description: The monthly rent you expect for a paid number, in micros (from the allowance). The purchase is refused with 409 if that has changed since you checked.
          example: 2000000
      description: Input for buying a phone number
    ReleasePhoneNumberResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Phone number ID
        released:
          type: boolean
          const: true
          description: Always true; the number is gone and rent has stopped
      required:
      - id
      - released
      description: Confirmation that a phone number was released
    PhoneNumberResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Phone number ID
        e164:
          type: string
          description: The number in E.164 format
          example: '+14155550123'
        name:
          type:
          - string
          - 'null'
          description: Label the project gave the number
        localityCode:
          type:
          - string
          - 'null'
          description: ISO 3166-2 code of the region the number is from, when the carrier gave one
        purchasedAt:
          type: string
          description: When the number was bought (ISO 8601)
        rentNextChargeAt:
          type: string
          description: When the next month of rent is due (ISO 8601)
        isFree:
          type: boolean
          description: Whether the number sits inside the plan free allowance right now
        monthlyRentMicros:
          type: integer
          description: What a month of this number costs in micro-dollars; 0 while it is free
        agentId:
          type:
          - string
          - 'null'
          format: uuid
          description: The agent the number is assigned to, if any
      required:
      - id
      - e164
      - name
      - localityCode
      - purchasedAt
      - rentNextChargeAt
      - isFree
      - monthlyRentMicros
      - agentId
      description: A phone number the project owns
    AvailablePhoneNumberResponse:
      type: object
      properties:
        e164:
          type: string
          description: The number in E.164 format
          example: '+14155550123'
        region:
          type:
          - string
          - 'null'
          description: Region the carrier lists, e.g. a state code
        locality:
          type:
          - string
          - 'null'
          description: Locality the carrier lists, e.g. a city
        bestEffort:
          type: boolean
          description: True when the area code asked for had no numbers and the carrier offered this nearby one instead
      required:
      - e164
      - region
      - locality
      - bestEffort
      description: A number the carrier has for sale
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT