Customer.io Identify API

openapi: 3.1.0
info:
  title: Customer.io App Activities Identify API
  description: The Customer.io App API enables developers to manage workspace resources and send messages programmatically. It provides endpoints for sending transactional messages, triggering broadcasts, managing customers and segments, retrieving campaign and newsletter data, and exporting customer information. The API uses bearer token authentication with an App API key and is designed for operations that go beyond data ingestion, such as retrieving metrics, managing message templates, and automating outbound communications from Customer.io.
  version: 1.0.0
  contact:
    name: Customer.io Support
    url: https://customer.io/contact
  termsOfService: https://customer.io/legal/terms-of-service
servers:
- url: https://api.customer.io/v1
  description: US Production Server
- url: https://api-eu.customer.io/v1
  description: EU Production Server
security:
- bearerAuth: []
tags:
- name: Identify
  description: Identify people and set their profile attributes. The identify call tells Customer.io who the current user is and assigns traits to them.
paths:
  /identify:
    post:
      operationId: identifyPerson
      summary: Identify a person
      description: Identifies a person and sets their profile attributes. Use this call when a user creates an account, logs in, or updates their profile. Requires at least one of userId or anonymousId. Traits are saved as profile attributes.
      tags:
      - Identify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyRequest'
      responses:
        '200':
          description: Person identified successfully.
        '400':
          description: Bad request. Missing required fields.
        '401':
          description: Unauthorized. Invalid CDP API key.
components:
  schemas:
    IdentifyRequest:
      type: object
      description: An identify call that assigns traits to a person.
      properties:
        userId:
          type: string
          description: The unique user identifier in your system.
        anonymousId:
          type: string
          description: An anonymous identifier for the user.
        traits:
          type: object
          description: Attributes to set on the person profile. Common traits include email, name, and plan.
          additionalProperties: true
          properties:
            email:
              type: string
              format: email
              description: The person email address.
            name:
              type: string
              description: The person full name.
            first_name:
              type: string
              description: The person first name.
            last_name:
              type: string
              description: The person last name.
            phone:
              type: string
              description: The person phone number.
            created_at:
              type: string
              format: date-time
              description: When the person account was created.
        context:
          $ref: '#/components/schemas/Context'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the identify call was made.
        messageId:
          type: string
          description: A unique identifier for this message for deduplication.
    Context:
      type: object
      description: Contextual information about the API call. Contains information about the device, library, and other environmental details.
      properties:
        ip:
          type: string
          description: The IP address of the user.
        locale:
          type: string
          description: The locale of the user.
        timezone:
          type: string
          description: The timezone of the user.
        userAgent:
          type: string
          description: The user agent string.
        library:
          type: object
          description: Information about the library making the call.
          properties:
            name:
              type: string
              description: The library name.
            version:
              type: string
              description: The library version.
        device:
          type: object
          description: Information about the user device.
          properties:
            id:
              type: string
              description: The device identifier.
            manufacturer:
              type: string
              description: The device manufacturer.
            model:
              type: string
              description: The device model.
            type:
              type: string
              description: The device type.
        os:
          type: object
          description: Information about the user operating system.
          properties:
            name:
              type: string
              description: The operating system name.
            version:
              type: string
              description: The operating system version.
        page:
          type: object
          description: Information about the current page for web contexts.
          properties:
            url:
              type: string
              format: uri
              description: The page URL.
            title:
              type: string
              description: The page title.
            referrer:
              type: string
              format: uri
              description: The referring URL.
            path:
              type: string
              description: The page path.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your App API key. Pass the key in the Authorization header as Bearer {app_api_key}.
externalDocs:
  description: App API Documentation
  url: https://docs.customer.io/integrations/api/app/