openapi: 3.0.0
paths:
  /api/v1/dncs:
    post:
      operationId: createDnc
      summary: Add phone numbers as do-not-contact (DNC) to Aktify for company
      description: Adds all provided phone numbers as DNC into Aktify for company.
      parameters:
        - name: x-api-key
          in: header
          description: The Aktify-provided API key.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDnc'
      responses:
        '201':
          description: The created DNCs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dnc'
  /api/v1/leads:
    post:
      operationId: createLead
      summary: Adds a lead to the campaign associated with the API key
      description: Adds a lead to the campaign associated with the API key.
      parameters:
        - name: x-api-key
          required: true
          in: header
          description: The Aktify-provided API key.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLead'
      responses:
        '201':
          description: The created lead with whatever properties were accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '400':
          description: >-
            Returned if required fields are missing or any provide field is
            invalid. Additional details may be in the response body but are not
            included in the API contract.
        '401':
          description: >-
            Returned if the request was not authorized with a valid x-api-key
            header. Additional details may be in the response body but are not
            included in the API contract.
        '409':
          description: >-
            Returned if the phone number was already submitted to the campaign.
            Additional details may be in the response body but are not included
            in the API contract.
  /api/v1/leads/end-contact:
    post:
      operationId: endContact
      summary: Ends contact with a lead for a company's given campaign
      description: >-
        Ends contact with a lead for a campaign upon company request. This does
        not create a DNC.
      parameters:
        - name: x-api-key
          required: true
          in: header
          description: The Aktify-provided API key.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndContact'
      responses:
        '201':
          description: >-
            Returns two lists, one for numbers that were successfully processed,
            and another list of phone numbers that failed to process correctly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndContactResult'
        '400':
          description: >-
            Returned if required fields are missing or any provide field is
            invalid. Additional details may be in the response body but are not
            included in the API contract.
        '401':
          description: >-
            Returned if the request was not authorized with a valid x-api-key
            header. Additional details may be in the response body but are not
            included in the API contract.
info:
  title: Aktify API
  description: These services allow Aktify customers to manage Leads, DNCs, and Webhooks
  version: v1
  contact: {}
tags: []
servers:
  - url: https://api.aktify.io
    description: Aktify API
components:
  schemas:
    Dnc:
      type: object
      properties:
        phoneNumber:
          type: string
          description: The phone number to mark as a DNC in Aktify for the company.
          example: (509) 555-1234
      required:
        - phoneNumber
    CreateDnc:
      type: object
      properties:
        dncList:
          description: The list of phone numbers to mark as DNC in Aktify for the company.
          example:
            - phoneNumber: (509) 555-1234
          type: array
          items:
            $ref: '#/components/schemas/Dnc'
      required:
        - dncList
    CreateLead:
      type: object
      properties:
        phoneNumber:
          type: string
          description: >-
            The phone number of the lead (equivalent to "phone" in the legacy
            leads_v2 API).
          example: (509) 555-1234
        region:
          type: string
          description: >-
            The region of the lead. Required if zipCode is not provided.
            Restricted to US state codes.
          example: CA
        zipCode:
          type: string
          description: >-
            The zip code of the lead. Required if region is not provided. Will
            be used to determine region.
          example: '90210'
        email:
          type: string
          description: The email of the lead
          example: someone@example.com
        externalCreated:
          type: string
          description: >-
            The external creation time of the lead in ISO8601 format (equivalent
            to "ext_created" in the legacy leads_v2 API). This attribute of the
            lead will be used if the campaign posting strategy is batched and
            prioritized earliest first or latest first by the lead creation
            time.
          example: 2022-11-15T21:04:28-0600
        externalLeadId:
          type: string
          description: >-
            The external lead ID of the lead (equivalent to "ext_lead_id" in the
            legacy leads_v2 API).
          example: myCustomLeadId
        firstName:
          type: string
          description: >-
            The first name of the lead (equivalent to "first_name" in the legacy
            leads_v2 API).
          example: John
        lastName:
          type: string
          description: >-
            The last name of the lead (equivalent to "last_name" in the legacy
            leads_v2 API).
          example: Smith
        source:
          type: string
          description: >-
            The source of the lead. This should be provided if you have
            configured your campaign outreach templates to use a LEAD_SOURCE
            replacement.
          example: myCustomSource
        link:
          type: string
          description: >-
            The link you would like to send to the lead. This should be provided
            if you are submitting a lead for a link-click campaign. Mutually
            exclusive parameter with "linkToShorten" (one or the other must be
            provided, but not both).
          example: https://www.aktify.com
        metadata:
          type: object
          description: >-
            Optional metadata associated with the lead. Must be a key-value
            object where all values are strings.
          example:
            customField1: value1
            customField2: value2
        linkToShorten:
          type: string
          description: >-
            The link you would like for Aktify to shorten, then send to the
            lead. This should be provided if you are submitting a lead for a
            link-click-with-click-tracking campaign. Mutually exclusive
            parameter with "link" (one or the other must be provided, but not
            both).
          example: https://www.aktify.com
      required:
        - phoneNumber
    Lead:
      type: object
      properties:
        phoneNumber:
          type: string
          description: >-
            The phone number of the lead (equivalent to "phone" in the legacy
            leads_v2 API).
          example: (509) 555-1234
        region:
          type: string
          description: >-
            The region of the lead. Required if zipCode is not provided.
            Restricted to US state codes.
          example: CA
        zipCode:
          type: string
          description: >-
            The zip code of the lead. Required if region is not provided. Will
            be used to determine region.
          example: '90210'
        email:
          type: string
          description: The email of the lead
          example: someone@example.com
        externalCreated:
          type: string
          description: >-
            The external creation time of the lead in ISO8601 format (equivalent
            to "ext_created" in the legacy leads_v2 API). This attribute of the
            lead will be used if the campaign posting strategy is batched and
            prioritized earliest first or latest first by the lead creation
            time.
          example: 2022-11-15T21:04:28-0600
        externalLeadId:
          type: string
          description: >-
            The external lead ID of the lead (equivalent to "ext_lead_id" in the
            legacy leads_v2 API).
          example: myCustomLeadId
        firstName:
          type: string
          description: >-
            The first name of the lead (equivalent to "first_name" in the legacy
            leads_v2 API).
          example: John
        lastName:
          type: string
          description: >-
            The last name of the lead (equivalent to "last_name" in the legacy
            leads_v2 API).
          example: Smith
        source:
          type: string
          description: >-
            The source of the lead. This should be provided if you have
            configured your campaign outreach templates to use a LEAD_SOURCE
            replacement.
          example: myCustomSource
        link:
          type: string
          description: The link that will be sent to the lead.
          example: https://shortlink.aktify.com/abcd1234
        metadata:
          type: object
          description: >-
            Optional metadata associated with the lead. Must be a key-value
            object where all values are strings.
          example:
            customField1: value1
            customField2: value2
      required:
        - phoneNumber
    EndContact:
      type: object
      properties:
        phoneNumberList:
          description: >-
            The list of phone numbers to end contact with in Aktify for the
            company. The entire request will fail if a phone number is not
            formatted correctly. Limited to a list of 50. Each phone number in
            the list must be unique.
          example:
            - (509) 555-1234
          type: array
          items:
            type: string
      required:
        - phoneNumberList
    EndContactResult:
      type: object
      properties:
        success:
          description: >-
            The list of phone numbers that successfully marked as end contact.
            The lead will not be outreached to unless they reach out first. The
            numbers will be in E.164 format. Numbers that were already submitted
            or if the lead has not been posted (outreached to) yet will be in
            the `success` field.
          example:
            - '+15095551234'
          type: array
          items:
            type: string
        failure:
          description: >-
            The list of phone numbers that failed to be marked as end contact.
            The numbers will be in E.164 format. This was likely due to a system
            error on our side, so feel free to retry. Notify us if the issue
            persists.
          example:
            - '+15095551234'
          type: array
          items:
            type: string
      required:
        - success
        - failure