> ## 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.

# List contacts

> Retrieve contacts from your Peoplewisher account. You can filter by Celebration Group, search, and paginate through results.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.peoplewisher.com/v1/contacts?page=1&per_page=100' \
    --header 'Authorization: Bearer YOUR_API_KEY' 
  ```
</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",
        "profile_image": null,
        "contact_status": "1",
        "birthday_month": 10,
        "birthday_day": 12,
        "birthday_year": 1994,
        "gender": null,
        "location": "Lagos",
        "timezone": "Africa/Lagos",
        "language": "en",
        "company": "Example Ltd",
        "job_title": "Finance Manager",
        "salutation": "Ms.",
        "relationship_status": null,
        "group_id": 24,
        "group_name": "Customers",
        "guardian_contact_id": null,
        "source": "api",
        "date_created": "2026-09-28 17:30:00",
        "date_updated": null
      }
    ],
    "todays_date": "28-09-2026",
    "fetched_record": 1,
    "total_records": 1,
    "page": 1,
    "per_page": 100,
    "has_more": false,
    "birthday_status": true
  }
  ```
</ResponseExample>

## How it works

### Query parameters

* `group_id` — Return only contacts belonging to a specific Celebration Group.
* `page` — Page number. Peoplewisher returns up to 100 contacts per page.
* `search` — Search contacts using the fields supported by PeopleWisher.

Use the `has_more` field to determine whether another page is available.

## 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 GET /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:
    get:
      tags:
        - Contacts
      summary: List contacts
      description: |
        Returns contacts belonging to the authenticated Peoplewisher account.
        Use `group_id` to return contacts in one Celebration Group.

        Results are paginated in pages of up to 100 records.
      operationId: listContacts
      parameters:
        - $ref: '#/components/parameters/GroupId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: Contact list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListResponse'
              example:
                success: true
                data:
                  - contact_id: 4812
                    first_name: Ada
                    last_name: Okafor
                    email: ada@example.com
                    phone: '+2348012345678'
                    whatsapp_phone: '+2348012345678'
                    profile_image: null
                    contact_status: '1'
                    birthday_month: 10
                    birthday_day: 12
                    birthday_year: 1994
                    gender: null
                    location: Lagos
                    timezone: Africa/Lagos
                    language: en
                    company: Example Ltd
                    job_title: Finance Manager
                    salutation: Ms.
                    relationship_status: null
                    group_id: 24
                    group_name: Customers
                    guardian_contact_id: null
                    source: api
                    date_created: '2026-09-28 17:30:00'
                    date_updated: null
                todays_date: 28-09-2026
                fetched_record: 1
                total_records: 1
                page: 1
                per_page: 100
                has_more: false
                birthday_status: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --request GET \
              --url 'https://api.peoplewisher.com/v1/contacts?page=1&per_page=100' \
              --header 'Authorization: Bearer YOUR_API_KEY' 
components:
  parameters:
    GroupId:
      name: group_id
      in: query
      required: false
      description: Restrict the contact list to a Celebration Group.
      schema:
        type: integer
        minimum: 1
    Page:
      name: page
      in: query
      required: false
      description: Page number. Results contain up to 100 contacts.
      schema:
        type: integer
        minimum: 1
        default: 1
    Search:
      name: search
      in: query
      required: false
      description: Search contacts by the fields supported by PeopleWisher.
      schema:
        type: string
  schemas:
    ContactListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        todays_date:
          type: string
        fetched_record:
          type: integer
        total_records:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        has_more:
          type: boolean
        birthday_status:
          type: boolean
          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
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
          nullable: true
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: unauthorized
            message: Invalid or missing API key.
    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.

````