> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Get Contacts > This endpoint retrieves a paginated list of contacts ## OpenAPI ````yaml GET /contacts openapi: 3.0.3 info: title: API - Local description: >- #### Welcome to the official Postman collection of Periskope API Periskope APIs enable you automate actions on your WhatsApp phone, and the Periskope platform - Read more about the APIs & webhooks here - [https://docs.periskope.app/api-reference/introduction](https://docs.periskope.app/api-reference/introduction) - We encourage responsible usage of the APIs. Follow these best practices and recommendations for safe actions on WhatsApp - [https://docs.periskope.app/get-started/best-practices](https://docs.periskope.app/get-started/best-practices) #### Getting Started ##### Pre-requisites: 1. **Sign up for a free account on Periskope:** To use the Periskope API, you need to have an active Periskope account. If you don’t have one, you can sign up for a 7-day free trial [here](https://console.periskope.app). 2. **Scan the QR code from WhatsApp to connect your phone:** A connected phone is required to use the APIs 3. **Go to** [Settings > API](https://console.periskope.app/settings/api), and generate an API key for your organization - The API key is used to authenticate every request. Please keep this secure ##### Using Postman: 1. **Fork the collection so you can edit values and test the APIs in your own postman environment:** To fork the collection, click on the three dots next to v1. Then click on create a fork (_shortcut: Ctrl + Alt + F)._ 2. **Update the value of the variables in the collection:** \- Update the API key with the key generated in Step 3 \- Update the phone number with your connected number. This number will be added to the `x-phone` header across requests It must be in the format of country code+number, with no special characters or spaces _e.g. +91 98745 32456 becomes 919874532456_ For any help or feedback, please contact us at [support@periskope.app](https://mailto:support@periskope.app), or ping us on [WhatsApp](https://what.sapp.link/periskope) version: 1.0.0 contact: {} servers: - url: https://api.periskope.app/v1 security: - bearerAuth: [] tags: - name: contacts - name: tickets - name: tasks - name: phones - name: message - name: queue - name: chats - name: group - name: members - name: webhooks - name: custom properties paths: /contacts: get: tags: - contacts summary: Get Contacts description: | This endpoint retrieves a paginated list of contacts operationId: getContacts parameters: - name: offset in: query schema: type: number example: '0' description: |- - The offset value for paginating the results - Default 0 - name: limit in: query schema: type: number example: '10' description: |- - The maximum number of contacts to retrieve - Default 2000 responses: '200': description: 200 OK headers: Access-Control-Allow-Origin: schema: type: string example: '*' Connection: schema: type: string example: keep-alive Content-Length: schema: type: string example: '4780' Date: schema: type: string example: Mon, 20 Jan 2025 15:21:32 GMT ETag: schema: type: string example: W/"12ac-FKWux6AG8sEdnaM5gz/o+6nWcZY" Keep-Alive: schema: type: string example: timeout=5 X-Powered-By: schema: type: string example: Express X-RateLimit-Limit: schema: type: string example: '10' X-RateLimit-Remaining: schema: type: string example: '9' X-RateLimit-Reset: schema: type: string example: '1737386494' x-periskope-org-id: schema: type: string example: 2997dd64-89bf-48d3-9a22-b314fca017e5 x-periskope-trace-id: schema: type: string example: 3a75d970-d742-11ef-af23-09e9e991f0f8 content: application/json: schema: type: object description: >- Note: `chat_ids` associated with a contact are not returned. You can fetch a specific contact by `contact_id` to get all `chat_ids` associated with it properties: from: type: number description: The starting index of the returned contacts to: type: number description: The ending index of the returned contacts count: type: number description: The total count of contacts. contacts: type: array description: >- An array of contact objects. Refer to [the contact object here](/api-reference/objects/the-contact-object) examples: 200 OK: value: contacts: - contact_color: '#7D9EF1' contact_id: 919289665999@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919289665999%40c.us.jpg?timestamp=1737373011790 contact_name: Periskope Sales contact_type: business is_imported: null is_internal: null is_my_contact: null is_wa_contact: true label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-20T11:36:51.793829+00:00' - contact_color: '#DC2626' contact_id: 919537851844@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919537851844%40c.us.jpg?timestamp=1737141387093 contact_name: Bk contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: false label_ids: label-ukjqhqngnakncalm: true label-wwfrdqogccexahnv: true labels: - label1 - label2 org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-20T08:52:04.760153+00:00' - contact_color: '#007BFC' contact_id: 6282123235653@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F6282123235653%40c.us.jpg?timestamp=1737358933768 contact_name: Periskope Indonesia contact_type: business is_imported: null is_internal: null is_my_contact: null is_wa_contact: false label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-20T07:42:13.777762+00:00' - contact_color: '#C4532D' contact_id: 447403688342@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F447403688342%40c.us.jpg?timestamp=1737357784557 contact_name: Periskope Business contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: true label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-20T07:23:04.572048+00:00' - contact_color: '#C4532D' contact_id: 918527184400@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F918527184400%40c.us.jpg?timestamp=1737277451340 contact_name: Support contact_type: user is_imported: null is_internal: true is_my_contact: null is_wa_contact: false label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-19T09:04:11.356664+00:00' - contact_color: '#5E47DE' contact_id: 919319622936@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919319622936%40c.us.jpg?timestamp=1737141392918 contact_name: null contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: false label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-17T19:16:32.921911+00:00' - contact_color: '#25D366' contact_id: 919877534373@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919877534373%40c.us.jpg?timestamp=1737141392917 contact_name: null contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: false label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-17T19:16:32.92187+00:00' - contact_color: '#7F66FF' contact_id: 918297136234@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F918297136234%40c.us.jpg?timestamp=1737141392020 contact_name: null contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: false label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-17T19:16:32.023889+00:00' - contact_color: '#02A698' contact_id: 919035577330@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F919035577330%40c.us.jpg?timestamp=1737141391951 contact_name: Yasin 3 contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: true label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-17T19:16:31.956806+00:00' - contact_color: '#9333EA' contact_id: 918904950033@c.us contact_image: >- https://storage.googleapis.com/periskope-images/2997dd64-89bf-48d3-9a22-b314fca017e5%2F918904950033%40c.us.jpg?timestamp=1737141390937 contact_name: null contact_type: user is_imported: null is_internal: null is_my_contact: null is_wa_contact: false label_ids: {} labels: [] org_id: 2997dd64-89bf-48d3-9a22-b314fca017e5 updated_at: '2025-01-17T19:16:30.940934+00:00' count: 10 from: 1 to: 10 '422': description: 422 Invalid Limit headers: Access-Control-Allow-Origin: schema: type: string example: '*' Connection: schema: type: string example: keep-alive Content-Length: schema: type: string example: '197' Date: schema: type: string example: Thu, 09 Jan 2025 09:08:02 GMT ETag: schema: type: string example: W/"c5-sOfQmoGHJ22vOJ8WnucWzYQT5DI" Keep-Alive: schema: type: string example: timeout=5 X-Powered-By: schema: type: string example: Express X-RateLimit-Limit: schema: type: string example: '10' X-RateLimit-Remaining: schema: type: string example: '9' X-RateLimit-Reset: schema: type: string example: '1736413684' org_id: schema: type: string example: 2997dd64-89bf-48d3-9a22-b314fca017e5 x-periskope-trace-id: schema: type: string example: 3afe7fa0-ce69-11ef-9fd2-914300695506 content: application/json: schema: type: object properties: code: type: string example: VALIDATION_ERROR fields: type: object properties: limit: type: object properties: message: type: string example: Limit should be less than 2000 value: type: string example: '10000' message: type: string example: Limit should be less than ${MAX_LIMIT} name: type: string example: Validation Error status: type: number example: 422 examples: 422 Invalid Limit: value: code: VALIDATION_ERROR fields: limit: message: Limit should be less than 2000 value: '10000' message: Limit should be less than ${MAX_LIMIT} name: Validation Error status: 422 x-codeSamples: - lang: TypeScript label: Node.js source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210' }); async function getContacts() { const response = await client.contact.getAll(); console.log(response); } getContacts(); - lang: cURL label: cURL source: | curl -X GET \ https://api.periskope.app/v1/contacts \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'x-phone: YOUR_PHONE_NUMBER' \ components: securitySchemes: bearerAuth: type: http scheme: bearer ````