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

# Who is this number

> For a screen-pop: the contact behind a number in any form it is typed (national or international), with its open tickets, the last five conversation summaries and the last call. 404 when nobody has the number. Requires contacts:read.



## OpenAPI

````yaml /api-reference/openapi-public.json get /contacts/lookup
openapi: 3.0.3
info:
  description: >-
    The API your own systems use: place and follow calls, have an AI agent call
    someone, run campaigns and get their results, keep contacts in step with
    your CRM, and receive signed webhooks. Authenticate with an integration key
    (Authorization: Bearer ft_...), used only from the IP addresses it allows.
  title: FireTone API
  version: 0.1.0
servers:
  - description: Your platform's API host
    url: https://{host}/api/v1
    variables:
      host:
        default: api.firet.one
security:
  - bearerAuth: []
tags:
  - name: Auth
  - description: >-
      Live calls and what can be done to them: hang up, hold, transfer, park,
      merge, monitor, whisper; the Desk's own call.
    name: Calls
  - description: 'Outbound campaigns: contacts, attempts, outcomes.'
    name: Campaigns
  - description: 'Customers: who called, what is known about them, and their memory.'
    name: Contacts
  - description: What was said on an AI call, and the review of it.
    name: Conversations
  - description: >-
      Your own systems: HTTP connections an IVR calls mid-call, and webhooks for
      call events. Tenant URLs must be public https addresses.
    name: Integrations
  - name: Live
  - name: Provisioning
  - name: Reporting
  - description: Tickets raised by people, agents and the API.
    name: Tickets
  - description: Messages left for an extension or a queue.
    name: Voicemail
paths:
  /contacts/lookup:
    get:
      tags:
        - Contacts
      summary: Who is this number
      description: >-
        For a screen-pop: the contact behind a number in any form it is typed
        (national or international), with its open tickets, the last five
        conversation summaries and the last call. 404 when nobody has the
        number. Requires contacts:read.
      operationId: getContactsLookup
      parameters:
        - in: query
          name: number
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/organisationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  contact:
                    $ref: '#/components/schemas/Contact'
                  last_call:
                    properties:
                      billsec:
                        type: integer
                      call_uuid:
                        type: string
                      direction:
                        type: string
                      started_at:
                        format: date-time
                        type: string
                    type: object
                  open_tickets:
                    items:
                      properties:
                        id:
                          type: string
                        priority:
                          type: string
                        ref:
                          type: integer
                        status:
                          type: string
                        subject:
                          type: string
                      type: object
                    type: array
                  recent_conversations:
                    items:
                      properties:
                        call_uuid:
                          type: string
                        id:
                          type: string
                        started_at:
                          format: date-time
                          type: string
                        summary:
                          type: string
                      type: object
                    type: array
                type: object
          description: OK
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    organisationId:
      description: Narrow to one organisation. Outside your scope returns 403.
      in: query
      name: organisation_id
      schema:
        format: uuid
        type: string
  schemas:
    Contact:
      properties:
        attributes:
          description: >-
            Tenant-owned structured fields: account number, language, plan.
            Distinct from memory, which is what was learned in conversation.
          type: object
        call_count:
          type: integer
        created_at:
          format: date-time
          type: string
        dnc:
          type: boolean
        e164:
          type: string
        external_ref:
          description: >-
            A CRM's own id for this contact (PUT
            /contacts/by-reference/{reference}).
          type: string
        first_seen:
          description: >-
            Not created_at: a contact may be imported from a CRM long before
            they ever call.
          format: date-time
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        last_seen:
          format: date-time
          nullable: true
          type: string
        name:
          type: string
        organisation_id:
          format: uuid
          type: string
      type: object
    Error:
      properties:
        error:
          properties:
            code:
              enum:
                - invalid_request
                - invalid_credentials
                - unauthenticated
                - forbidden
                - not_found
                - conflict
                - internal
              type: string
            message:
              type: string
          required:
            - code
            - message
          type: object
      required:
        - error
      type: object
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Not found, or not visible to the caller
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT or API key
      description: >-
        Every request sends `Authorization: Bearer <token>`. The token is either
        a panel session (a JWT from /auth/login, 12 hours) or an API key
        `ft_<id>_<secret>`. An API key is accepted only from an address on its
        IP allowlist (403 ip_not_allowed otherwise; 403 ip_allowlist_required
        for an old key that has none), is limited to its rate per minute (429
        rate_limited with Retry-After; X-RateLimit-Limit/Remaining/Reset on
        every response), and at most 60 call placements a minute.
      scheme: bearer
      type: http

````