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

# Create a contact

> Create a contact and assign it to a Celebration Group. Once the contact is in the group, Peoplewisher handles the configured celebration workflow.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.peoplewisher.com/v1/contacts' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "first_name": "Ada",
      "last_name": "Okafor",
      "email": "ada@example.com",
      "phone": "+2348012345678",
      "whatsapp_phone": "+2348012345678",
      "birthday": "1994-10-12",
      "timezone": "Africa/Lagos",
      "location": "Lagos",
      "company": "Example Ltd",
      "job_title": "Finance Manager",
      "group_id": 24
    }' 
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": {
      "contact_id": 4812,
      "first_name": "Ada",
      "last_name": "Okafor",
      "email": "ada@example.com",
      "phone": "+2348012345678",
      "whatsapp_phone": "+2348012345678",
      "birthday": "1994-10-12",
      "timezone": "Africa/Lagos",
      "group_id": 24,
      "group_name": "Customers",
      "source": "api"
    }
  }
  ```
</ResponseExample>

## How it works

### Required fields

`first_name` and `group_id` are required. The `group_id` determines which celebration category and workflow applies to the contact.

You do not need to create a template, configure a message, or schedule an automation through the API. Configure those settings in Peoplewisher once, then use the API to keep contacts synchronized.

## Authentication

Include your Peoplewisher API key as a Bearer token on every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Your API key is available in **Peoplewisher → Settings → API**. Keep it private and never expose it in browser-side code or public repositories.


## OpenAPI

````yaml openapi.yaml POST /contacts
openapi: 3.0.3
info:
  title: Peoplewisher API
  version: 1.0.0
  description: |
    The Peoplewisher API lets an application synchronize contacts and place
    those contacts into Peoplewisher Celebration Groups. Peoplewisher then
    runs the celebration workflows configured for those groups in the
    Peoplewisher application.

    The public API is intentionally focused: applications provide people data
    and group membership. Templates, channels, schedules, celebration
    settings, and workflow behavior are managed in the Peoplewisher UI.
servers:
  - url: https://api.peoplewisher.com/v1
    description: Peoplewisher API
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Manage the people whose celebrations Peoplewisher handles.
  - name: Celebration Groups
    description: >-
      Manage the Peoplewisher groups that determine which celebration workflow
      applies to a contact.
paths:
  /contacts:
    post:
      tags:
        - Contacts
      summary: Create a contact
      description: |
        Creates a contact and assigns it to a Celebration Group.

        Adding a contact to a group is the action that connects the contact to
        the celebration workflow configured for that group. Once the contact
        exists, PeopleWisher's existing workflow engine takes over.

        A contact cannot be created without a `group_id`.
      operationId: createContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
            example:
              first_name: Ada
              last_name: Okafor
              email: ada@example.com
              phone: '+2348012345678'
              whatsapp_phone: '+2348012345678'
              birthday: '1994-10-12'
              timezone: Africa/Lagos
              location: Lagos
              company: Example Ltd
              job_title: Finance Manager
              group_id: 24
      responses:
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactMutationResponse'
              example:
                success: true
                data:
                  contact_id: 4812
                  first_name: Ada
                  last_name: Okafor
                  email: ada@example.com
                  phone: '+2348012345678'
                  whatsapp_phone: '+2348012345678'
                  birthday: '1994-10-12'
                  timezone: Africa/Lagos
                  group_id: 24
                  group_name: Customers
                  source: api
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/PlanLimit'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            A contact with the same phone number or email already exists in the
            group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: contact_exists
                message: >-
                  A contact with this phone number or email already exists in
                  this group.
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --request POST \
              --url 'https://api.peoplewisher.com/v1/contacts' \
              --header 'Authorization: Bearer YOUR_API_KEY' \
              --header 'Content-Type: application/json' \
              --data '{
                "first_name": "Ada",
                "last_name": "Okafor",
                "email": "ada@example.com",
                "phone": "+2348012345678",
                "whatsapp_phone": "+2348012345678",
                "birthday": "1994-10-12",
                "timezone": "Africa/Lagos",
                "location": "Lagos",
                "company": "Example Ltd",
                "job_title": "Finance Manager",
                "group_id": 24
              }' 
components:
  schemas:
    ContactCreate:
      type: object
      required:
        - first_name
        - group_id
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
          description: Primary phone number.
        whatsapp_phone:
          type: string
        birthday:
          type: string
          format: date
          description: >-
            Birthday in YYYY-MM-DD format. The year may be omitted when only
            month/day are known.
        timezone:
          type: string
          example: Africa/Lagos
        gender:
          type: string
        location:
          type: string
        language:
          type: string
        company:
          type: string
        job_title:
          type: string
        salutation:
          type: string
        relationship_status:
          type: string
        guardian_contact_id:
          type: integer
        profile_image:
          type: string
          description: URL or PeopleWisher-supported profile image reference.
        status:
          type: string
          default: '1'
        group_id:
          type: integer
          minimum: 1
        custom_fields:
          type: object
          additionalProperties: true
    ContactMutationResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Contact'
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
          nullable: true
    Contact:
      type: object
      properties:
        contact_id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
          nullable: true
        phone:
          type: string
          nullable: true
        whatsapp_phone:
          type: string
          nullable: true
        profile_image:
          type: string
          nullable: true
        contact_status:
          type: string
        birthday_month:
          type: integer
          nullable: true
        birthday_day:
          type: integer
          nullable: true
        birthday_year:
          type: integer
          nullable: true
        gender:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        timezone:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        job_title:
          type: string
          nullable: true
        salutation:
          type: string
          nullable: true
        relationship_status:
          type: string
          nullable: true
        group_id:
          type: integer
          nullable: true
        group_name:
          type: string
          nullable: true
        guardian_contact_id:
          type: integer
          nullable: true
        source:
          type: string
        date_created:
          type: string
        date_updated:
          type: string
          nullable: true
  responses:
    InvalidRequest:
      description: The request is malformed or required data is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: invalid_request
            message: A valid group_id is required.
    PlanLimit:
      description: The account has reached a Peoplewisher plan limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: plan_limit_reached
            message: >-
              You have reached the maximum number of contacts allowed on your
              current plan.
    NotFound:
      description: The requested resource does not exist in the authenticated account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: not_found
            message: Contact not found.
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: validation_error
            message: Please provide a valid email address.
    RateLimited:
      description: The API request was rate limited.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: rate_limited
            message: Too many requests. Please retry later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: |
        Use the API key generated in Peoplewisher Settings as a Bearer token.

````