> ## Documentation Index > Fetch the complete documentation index at: https://docs.watx.in/llms.txt > Use this file to discover all available pages before exploring further. # Add contacts to a segment > Adds contacts to a **static** segment. A dynamic segment answers `400` — its membership comes from its filter. Up to 1000 contact ids per request. `added` counts the rows actually created, so ids that were already members and ids belonging to another workspace both count as zero — compare it with `requested`. Requires the `contacts:write` scope. ## OpenAPI ````yaml /openapi.yaml post /segments/{id}/contacts openapi: 3.1.0 info: title: Watx API version: '1' description: | The Watx public REST API. Send WhatsApp messages, manage contacts and segments, read conversations and messages, launch broadcasts, and register webhook endpoints. Every request authenticates with a workspace API key sent as a bearer token. A key acts on exactly one workspace and can only do what its scopes allow. Each operation below names the scope it requires. contact: name: Watx support email: support@watx.in servers: - url: https://api.watx.in/v1 description: Production security: - apiKey: [] tags: - name: Account description: Check which workspace a key belongs to and what it can do. - name: Messages description: Send a WhatsApp message to a phone number. - name: Contacts description: Create, read, update and list contacts. - name: Conversations description: Read conversations and their messages. - name: Broadcasts description: Launch a template broadcast and follow its progress. - name: Segments description: Named audiences — static lists and saved filters. - name: Webhooks description: Register endpoints that receive events from your workspace. paths: /segments/{id}/contacts: parameters: - $ref: '#/components/parameters/segmentId' post: tags: - Segments summary: Add contacts to a segment description: | Adds contacts to a **static** segment. A dynamic segment answers `400` — its membership comes from its filter. Up to 1000 contact ids per request. `added` counts the rows actually created, so ids that were already members and ids belonging to another workspace both count as zero — compare it with `requested`. Requires the `contacts:write` scope. operationId: addSegmentContacts requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SegmentContactsRequest' example: contact_ids: - 7e2d9c01-55b4-4a3d-9c8e-0f1a2b3c4d5e - 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d responses: '201': description: How many of the requested contacts were added. content: application/json: schema: type: object properties: data: type: object properties: segment_id: type: string format: uuid requested: type: integer added: type: integer example: data: segment_id: 8c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f requested: 2 added: 1 '400': description: | An empty or oversized `contact_ids`, or a dynamic segment. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: >- Cannot add contacts to a dynamic segment; its membership comes from its filter '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: segmentId: name: id in: path required: true description: The segment id. schema: type: string format: uuid schemas: SegmentContactsRequest: type: object required: - contact_ids properties: contact_ids: type: array minItems: 1 maxItems: 1000 items: type: string format: uuid Error: type: object description: | Every failure uses this shape. Branch on `error.code`, which is stable; `error.message` is written for people and may be reworded. required: - error properties: error: type: object required: - code - message properties: code: type: string description: | One of `bad_request`, `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `internal`, or a domain code such as `whatsapp_not_configured`, `meta_error`, `template_malformed`, `plan_limit_reached`, `subscription_lapsed`. example: bad_request message: type: string example: '''phone'' is required' responses: Unauthorized: description: | The key is missing, malformed, unknown, revoked or expired. All four answer the same way. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Missing or invalid API key Forbidden: description: The key is valid but was not granted the scope this operation requires. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: This API key is missing the 'messages:send' scope NotFound: description: | No such resource in this workspace. A resource belonging to another workspace answers the same way. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Contact not found RateLimited: description: | More than 120 requests in a minute for this key. `Retry-After` says how many seconds to wait. headers: Retry-After: description: Seconds until the window resets. schema: type: integer X-RateLimit-Limit: description: Requests allowed per window. schema: type: integer X-RateLimit-Remaining: description: Requests left in this window. schema: type: integer X-RateLimit-Reset: description: Unix time in seconds when the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Rate limit exceeded for this API key securitySchemes: apiKey: type: http scheme: bearer description: | Your workspace API key, created in **Settings → API keys**, sent as `Authorization: Bearer `. New keys start with `watx_live_`; keys issued before the rename start with `converse360_live_` and still work. ````