openapi: 3.0.0
info:
  description: |
    Understand general concepts, response codes, and authentication strategies.

    ## Base URL
    The Pingback API is built on **REST** principles. We enforce **HTTPS** in every request to improve data security, integrity, and privacy. The API does not support **HTTP**.

    All requests contain the following base URL:

    ```
    https://connect.pingback.com/v1
    ```

    ---

    ## Authentication

    The Pingback API uses API keys to authenticate requests. You can request and manage your API keys with our [**support team**](https://helpcenter.pingback.com/).

    To authenticate you need to add an Authorization header with the contents of the header being `x-api-key: ***` where `***` is your API Key.

    ```
    x-api-key: ***
    ```

    Your API key is unique to your account and should be kept secure. Do not share your API key in publicly accessible areas such as GitHub, client-side code, and so on.

    We also encrypt your API key in our database to ensure that it is secure, using `AES-256` encryption.

    ---

    ## Response Codes

    Pingback uses standard HTTP codes to indicate the success or failure of your requests.

    In general, `2xx` HTTP codes correspond to success, `4xx` codes are for user-related failures, and `5xx` codes are for infrastructure issues.

    | Code   | Description |
    | ------ | ----------- |
    | `200`  | OK          |
    | `201`  | Created     |
    | `403`  | Forbidden   |
    | `404`  | Not Found   |
    | `409`  | Conflict    |
    | `422`  | Unprocessable Entity |
    | `429`  | Too Many Requests |
    | `500`  | Internal Server Error |

    ---

    ## Rate Limiting

    Pingback enforces rate limits to ensure fair usage of the API. If you exceed the rate limit, you will receive a `429` status code.

    The maximum number of requests that users can send is **5 requests per second**.

    The burst rate is **2 requests** at a time.

    To prevent this, we recommend reducing the rate at which you request the API. This can be done by introducing a queue mechanism or reducing the number of concurrent requests per second. If you have specific requirements, contact [**support team**](https://helpcenter.pingback.com/).

    ---

    ## Developer Mode

    The Pingback API has a developer mode that allows you to test your integrations without affecting your production data. To enable developer mode, you need to add a header to your request.

    ```
    x-developer-mode: true
    ```

    This mode is useful for testing your integrations and ensuring that your code is working as expected. All the data returned in developer mode is fake and does not affect your production data.

    ---

    ## Support

    If you have any questions or need help, please contact our [**support team**](https://helpcenter.pingback.com/).

    Each request to the API will return a `requestId` inside the body. If you need to contact support, please provide this `requestId` to help us identify your request.

  version: 1.0.0
  title: Introduction
servers:
  - url: "https://connect.pingback.com/v1"
externalDocs:
  description: Pingback API documentation
  url: "https://github.com/getpingback/pingback-for-devs"
tags:
  - name: subscribers
    description: Manage your Pingback subscribers.
    x-displayName: Subscribers
  - name: segmentations
    description: Manage your Pingback segmentation lists.
    x-displayName: Segmentations
paths:
  /subscriber:
    parameters:
      - name: x-developer-mode
        in: header
        description: Enable developer mode. Learn more [here](/docs/api/introduction#developer-mode).
        required: false
        schema:
          type: boolean
      - name: x-api-key
        in: header
        description: Your API key
        required: true
        schema:
          type: string
    post:
      tags:
        - subscribers
      summary: Create a subscriber
      description: Create a new subscriber
      operationId: createSubscriber
      responses:
        "201":
          description: Subscriber created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Subscriber"
                  requestId:
                    type: string
        "400":
          description: Body is necessary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Body is necessary.
                  errorCode:
                    type: string
                    example: MISSING_BODY
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "404":
          description: Segmentation list not found. Only when passing a segmentation list that does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Segmentation list not found.
                  errorCode:
                    type: string
                    example: SEGMENTATION_LIST_NOT_FOUND
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "409":
          description: Subscriber already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Subscriber already exists.
                  errorCode:
                    type: string
                    example: SUBSCRIBER_ALREADY_EXISTS
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "422":
          description: Unprocessable Entity.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid email address.
                  errorCode:
                    type: string
                    example: INVALID_INPUT
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error.
                  errorCode:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
      requestBody:
        $ref: "#/components/requestBodies/Subscriber"

  "/subscriber/{email}":
    parameters:
      - name: x-api-key
        in: header
        description: Your API key
        required: true
        schema:
          type: string
      - name: x-developer-mode
        in: header
        description: Enable developer mode. Learn more [here](/docs/api/introduction#developer-mode).
        required: false
        schema:
          type: boolean
      - name: email
        in: path
        description: Subscriber email address
        required: true
        schema:
          type: string
    get:
      tags:
        - subscribers
      summary: Get a subscriber
      description: Get a subscriber by email
      operationId: getSubscriber
      responses:
        "200":
          description: Subscriber found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Subscriber"
                  requestId:
                    type: string
        "404":
          description: Subscriber not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Subscriber not found.
                  errorCode:
                    type: string
                    example: SUBSCRIBER_NOT_FOUND
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error.
                  errorCode:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
    put:
      tags:
        - subscribers
      summary: Update a subscriber
      description: Update a subscriber by email
      operationId: updateSubscriber
      responses:
        "200":
          description: Subscriber updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Subscriber"
                  requestId:
                    type: string
        "404":
          description: Subscriber not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Subscriber not found.
                  errorCode:
                    type: string
                    example: SUBSCRIBER_NOT_FOUND
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error.
                  errorCode:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Subscriber name
                  type: string
                  example: John Doe
                phone:
                  description: Subscriber phone number. It follows the E.164 format.
                  type: string
                  format: phone
                  example: "+5511999999999"
                status:
                  description: Subscriber status
                  type: string
                  enum:
                    - free_subscriber
                    - paid_subscriber
                    - unsubscribed_subscriber
                  example: free_subscriber

  "/segmentation/add-subscriber/{email}":
    parameters:
      - name: x-api-key
        in: header
        description: Your API key
        required: true
        schema:
          type: string
      - name: x-developer-mode
        in: header
        description: Enable developer mode. Learn more [here](/docs/api/introduction#developer-mode).
        required: false
        schema:
          type: boolean
      - name: email
        in: path
        description: Subscriber email address
        required: true
        schema:
          type: string
    post:
      tags:
        - segmentations
      summary: Add a subscriber to segmentation lists
      description: Add a subscriber to segmentation lists by email
      operationId: addSubscriberToSegment
      responses:
        "200":
          description: Subscriber added to segmentation list
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        email:
                          type: string
                        subscriberId:
                          type: string
                        segmentationListId:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                anyOf:
                  - title: Body is necessary
                    type: object
                    properties:
                      error:
                        type: string
                        example: Body is necessary
                      errorCode:
                        type: string
                        example: MISSING_BODY
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
                  - title: Subscriber not enabled
                    type: object
                    properties:
                      error:
                        type: string
                        example: Subscriber not enabled
                      errorCode:
                        type: string
                        example: SUBSCRIBER_NOT_ENABLED
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "404":
          description: Not found
          content:
            application/json:
              schema:
                anyOf:
                  - title: Subscriber not found
                    type: object
                    properties:
                      error:
                        type: string
                        example: Subscriber not found
                      errorCode:
                        type: string
                        example: SUBSCRIBER_NOT_FOUND
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
                  - title: Segmentation list not found
                    type: object
                    properties:
                      error:
                        type: string
                        example: Segmentation list not found
                      errorCode:
                        type: string
                        example: SEGMENTATION_LIST_NOT_FOUND
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                anyOf:
                  - title: Subscriber email is necessary
                    type: object
                    properties:
                      error:
                        type: string
                        example: Subscriber email is necessary
                      errorCode:
                        type: string
                        example: SUBSCRIBER_EMAIL_IS_NECESSARY
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
                  - title: Unprocessable Entity
                    type: object
                    properties:
                      error:
                        type: string
                        example: Unprocessable Entity.
                      errorCode:
                        type: string
                        example: INVALID_INPUT
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error.
                  errorCode:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                segmentationLists:
                  description: List of segmentation lists IDs. You can get the ID by calling our support team.
                  type: array
                  items:
                    type: string
                  example: ["ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f", "ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f"]

  "/segmentation/{id}/remove-subscriber/{email}":
    parameters:
      - name: x-api-key
        in: header
        description: Your API key
        required: true
        schema:
          type: string
      - name: x-developer-mode
        in: header
        description: Enable developer mode. Learn more [here](/docs/api/introduction#developer-mode).
        required: false
        schema:
          type: boolean
      - name: id
        in: path
        description: Segmentation list ID
        required: true
        schema:
          type: string
      - name: email
        in: path
        description: Subscriber email address
        required: true
        schema:
          type: string
    delete:
      tags:
        - segmentations
      summary: Remove a subscriber from a segmentation list
      description: Remove a subscriber from a segmentation list by email
      operationId: removeSubscriberFromSegment
      responses:
        "200":
          description: Subscriber removed from segmentation list
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                      subscriberId:
                        type: string
                      segmentationListId:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        "400":
          description: Subscriber not enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Subscriber not enabled
                  errorCode:
                    type: string
                    example: SUBSCRIBER_NOT_ENABLED
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "404":
          description: Not found
          content:
            application/json:
              schema:
                anyOf:
                  - title: Subscriber not found
                    type: object
                    properties:
                      error:
                        type: string
                        example: Subscriber not found
                      errorCode:
                        type: string
                        example: SUBSCRIBER_NOT_FOUND
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
                  - title: Segmentation list not found
                    type: object
                    properties:
                      error:
                        type: string
                        example: Segmentation list not found
                      errorCode:
                        type: string
                        example: SEGMENTATION_LIST_NOT_FOUND
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                anyOf:
                  - title: Segmentation id is required
                    type: object
                    properties:
                      error:
                        type: string
                        example: Segmentation id is required
                      errorCode:
                        type: string
                        example: SUBSCRIBER_EMAIL_IS_NECESSARY
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
                  - title: Subscriber email is necessary
                    type: object
                    properties:
                      error:
                        type: string
                        example: Subscriber email is necessary
                      errorCode:
                        type: string
                        example: SUBSCRIBER_EMAIL_IS_NECESSARY
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
                  - title: Unprocessable Entity
                    type: object
                    properties:
                      error:
                        type: string
                        example: Unprocessable Entity.
                      errorCode:
                        type: string
                        example: INVALID_INPUT
                      requestId:
                        type: string
                        example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error.
                  errorCode:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  requestId:
                    type: string
                    example: ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f
components:
  schemas:
    CustomFields:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            readOnly: true
            description: Custom field ID
          label:
            type: string
            example: age
            description: Custom field label
          value:
            type: string
            example: 25
            description: Custom field value
    SegmentationLists:
      type: array
      items:
        type: string
    Subscriber:
      type: object
      required:
        - email
      properties:
        id:
          type: string
          readOnly: true
        email:
          description: Subscriber email address
          type: string
          format: email
          example: example@email.com
        phone:
          description: Subscriber phone number. It follows the E.164 format.
          type: string
          format: phone
          example: "+5511999999999"
        name:
          description: Subscriber name
          type: string
          example: John Doe
        status:
          description: Subscriber status
          type: string
          enum:
            - free_subscriber
            - paid_subscriber
            - unsubscribed_subscriber
          example: free_subscriber
        customFields:
          description: List of custom fields. Each custom field has a label, and value.
          $ref: "#/components/schemas/CustomFields"
        segmentationLists:
          description: List of segmentation lists IDs. You can get the ID by calling our support team.
          $ref: "#/components/schemas/SegmentationLists"
          example: ["ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f", "ff37b0a8-de19-4f72-a7ed-0bd1cb73f29f"]
        blacklistedAt:
          description: Subscriber blacklisted date
          type: string
          format: date-time
          readOnly: true
        unsubscribedAt:
          description: Subscriber unsubscribed date
          type: string
          format: date-time
          readOnly: true
        createdAt:
          description: Subscriber creation date
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          description: Subscriber update date
          type: string
          format: date-time
          readOnly: true
  requestBodies:
    Subscriber:
      content:
        application/json:
          schema:
            allOf:
              - description: Subscriber object
                title: Subscriber
              - $ref: "#/components/schemas/Subscriber"
      description: Subscriber object
      required: true