openapi: 3.0.0
info:
  title: Hatch contacts API
  version: '1.0'
servers:
- url: https://api.usehatchapp.com
  variables: {}
security:
- authorization: []
tags:
- name: contacts
paths:
  /v1/contacts:
    post:
      callbacks: {}
      description: "We will try to create a new contact, and in case that conflicts with an existent one we will update the contact.\n\nThe primary conflict targets are the attributes `phoneNumber` and `email` (with precedence following the listing below).\n\n  1. If the contact `phoneNumber` already exists, we update the contact with the new attribute values.\n  2. If the contact `email` already exists, we update the contact with the new attribute values.\n  3. Neither the `phoneNumber` nor `email` exists we create a new contact generating a new `ID` for that contact.\n\nWe also have a special behavior on the attribute `externalID`.\n\nExternal ID is a unique record identifier from the customer's external system.\nThis value must be unique among all opportunities on a contact (if provided).\nTherefore, an opportunity will be updated if data is ingested with a matching External ID value.\n"
      operationId: HatchWeb.V1.Integrations.ContactController.upsert (2)
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactParams'
        description: Contact upsert params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertContactSuccessfulResponse'
          description: Contact upsert success response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
      summary: Upsert a contact.
      tags:
      - contacts
    put:
      callbacks: {}
      description: "We will try to create a new contact, and in case that conflicts with an existent one we will update the contact.\n\nThe primary conflict targets are the attributes `phoneNumber` and `email` (with precedence following the listing below).\n\n  1. If the contact `phoneNumber` already exists, we update the contact with the new attribute values.\n  2. If the contact `email` already exists, we update the contact with the new attribute values.\n  3. Neither the `phoneNumber` nor `email` exists we create a new contact generating a new `ID` for that contact.\n\nWe also have a special behavior on the attribute `externalID`.\n\nExternal ID is a unique record identifier from the customer's external system.\nThis value must be unique among all opportunities on a contact (if provided).\nTherefore, an opportunity will be updated if data is ingested with a matching External ID value.\n"
      operationId: HatchWeb.V1.Integrations.ContactController.upsert
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactParams'
        description: Contact upsert params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertContactSuccessfulResponse'
          description: Contact upsert success response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
      summary: Upsert a contact.
      tags:
      - contacts
components:
  schemas:
    JsonErrorResponse:
      properties:
        errors:
          items:
            properties:
              detail:
                example: null value where string expected
                type: string
              source:
                properties:
                  pointer:
                    example: /data/attributes/petName
                    type: string
                required:
                - pointer
                type: object
              title:
                example: Invalid value
                type: string
            required:
            - title
            - source
            - detail
            type: object
          type: array
      required:
      - errors
      title: JsonErrorResponse
      type: object
    UpsertContactParams:
      description: The attributes for upserting a contact.
      example:
        details:
          address: contact address
          favoriteColor: Blue
        email: firstName.lastName@host.com
        externalContactID: c1dddbd0-a0d6-477c-815f-30c56312d5dc
        externalCreatedAt: '2023-02-06 17:46:25Z'
        externalID: 03775ccb-ffd7-48a6-b1c6-0fac96289928
        externalUpdatedAt: '2023-02-06 17:46:25Z'
        firstName: firstName
        lastName: lastName
        phoneNumber: '6364618187'
        source: custom:my-awesome-source
        status: sold
      properties:
        details:
          additionalProperties: true
          description: Any additional contact details you may want to include, commonly used for custom-fields.
          type: object
        email:
          description: The contact's email
          format: email
          nullable: true
          type: string
        externalContactID:
          description: The contact ID from your system.
          nullable: true
          type: string
        externalCreatedAt:
          description: The contact's creation timestamp from your system (ISO 8601). If not given Hatch defaults to the current time Hatch is processing the contact.
          format: date-time
          nullable: true
          type: string
        externalID:
          description: The lead ID from your system.
          nullable: true
          type: string
        externalUpdatedAt:
          description: The contact's updated timestamp from your system (ISO 8601).
          format: date-time
          nullable: true
          type: string
        firstName:
          description: The contact's first name.
          nullable: true
          type: string
        lastName:
          description: The contact's last name.
          nullable: true
          type: string
        phoneNumber:
          description: The contact's phone number.
          nullable: true
          type: string
        source:
          description: 'The source of the contact.


            This is used to identify the source of the contact for building audience segments.

            The source must be included in the list of the sources you have configured on Hatch platform.

            '
          type: string
        status:
          description: The contact's status from your system (This can be whatever is helpful for your workflow).
          nullable: true
          type: string
      title: UpsertContactParams
      type: object
    UpsertContactSuccessfulResponse:
      description: Response for upserting a contact with success
      example:
        data:
          id: 4856cea1-0fdc-458b-9e76-57b9bbd4c891
      properties:
        data:
          description: Data Representation
          properties:
            id:
              description: Contact ID
              type: string
          type: object
      title: UpsertContactSuccessfulResponse
      type: object
  securitySchemes:
    authorization:
      scheme: bearer
      type: http