> ## Documentation Index
> Fetch the complete documentation index at: https://dev.smile.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update a customer identity

> Creates a new customer identity or updates an existing one.

export const scope_0 = "customer_identity:write"

<Callout icon="key" iconType="regular">
  This endpoint requires the **{scope_0}** scope.
</Callout>

<Warning>
  This endpoint is only available to [apps](/guides/apps/build) making calls using an OAuth token. Attempting to use this endpoint with an API key will fail.
</Warning>

**Creating:** If no customer identity exists with the provided `distinct_id`, a new customer identity is created.

* If the provided email matches an existing customer record, the customer identity is linked to that customer.
* If the provided email does not match an existing customer record, a new customer is created and a customer identity is linked to the new customer.

**Updating:** If a customer identity exists with the provided `distinct_id`, it is updated with any new information provided in the request.

* No changes to the linked customer record will occur.


## OpenAPI

````yaml schemas/rest-api.json POST /customer_identities/create_or_update
openapi: 3.1.0
info:
  title: Smile.io REST API
  version: 1.0.0
  description: A RESTful interface for interacting with Smile.io loyalty programs.
servers:
  - url: https://api.smile.io/v1
security:
  - bearerAuth: []
paths:
  /customer_identities/create_or_update:
    post:
      tags:
        - Customer Identities
      summary: Create or update a customer identity
      description: Creates a new customer identity or updates an existing one.
      operationId: post__customer_identities_create_or_update
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_identity:
                  type: object
                  properties:
                    first_name:
                      type: string
                      description: The first name of the customer in the external system.
                      example: Jane
                    last_name:
                      type: string
                      description: The last name of the customer in the external system.
                      example: Doe
                    email:
                      type: string
                      format: email
                      example: jane@doe.com
                      description: The email of the customer in the external system.
                    distinct_id:
                      type: string
                      example: cust_19238475
                      description: >-
                        The unique identifier for the customer in the external
                        system.
                    properties:
                      type: object
                      description: >-
                        A restricted hash of additional attributes for the
                        customer identity. Keys are allowlisted on a
                        per-integration basis.
                  required:
                    - email
                    - distinct_id
              required:
                - customer_identity
      responses:
        '200':
          description: Customer identity successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_identity:
                    $ref: '#/components/schemas/CustomerIdentity'
        '201':
          description: Customer identity successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_identity:
                    $ref: '#/components/schemas/CustomerIdentity'
components:
  schemas:
    CustomerIdentity:
      type: object
      properties:
        id:
          type: integer
          example: 863291377
          description: Unique identifier for the customer identity in Smile.
        first_name:
          type:
            - string
            - 'null'
          example: Jane
          description: The first name of the customer in the external system.
        last_name:
          type:
            - string
            - 'null'
          example: Doe
          description: The last name of the customer in the external system.
        email:
          type: string
          format: email
          example: jane@doe.com
          description: The email of the customer in the external system.
        distinct_id:
          type: string
          example: cust_19238475
          description: The unique identifier for the customer in the external system.
        properties:
          type: object
          description: >-
            A restricted hash of additional attributes for the customer
            identity. Keys are allowlisted on a per-integration basis.
        customer_id:
          type: integer
          description: >-
            The ID of the customer in Smile that this customer identity is
            linked to.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````