> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt > Use this file to discover all available pages before exploring further. # Create or update contact > Upsert a contact by phoneNumber within the authorized channel. channelId is verified against channels owned by this API key — passing another workspace channelId is rejected (no cross-tenant write). Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_write — 30 requests/min per API user. ## OpenAPI ````yaml /api-reference/workspace.openapi.json post /api/workspace/v1/contacts/manage openapi: 3.1.0 info: title: Workspace API version: 1.0.0 description: >- Manage contacts, labels, custom fields, WhatsApp messaging, and automations for your workspace. Generate your API key in the Developer Portal (profile menu → Developer) and send it in the `X-API-Key` header, or as `Authorization: Bearer `. Never put the key in the URL. Every endpoint accepts POST with a JSON body, and also accepts GET with the same parameters as query-string values. All responses use the envelope `{ success, data?, message?, error? }`. servers: - url: https://YOUR_DOMAIN description: Your deployment, for example https://app.example.com security: [] tags: - name: Channels - name: Contacts - name: Custom Fields - name: Labels - name: WhatsApp - name: Automations paths: /api/workspace/v1/contacts/manage: post: tags: - Contacts summary: Create or update contact description: >- Upsert a contact by phoneNumber within the authorized channel. channelId is verified against channels owned by this API key — passing another workspace channelId is rejected (no cross-tenant write). Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_write — 30 requests/min per API user. parameters: - name: channelId in: query required: false description: Channel id. Auto-selects the first active channel when omitted. schema: type: string example: ch_123 - name: phoneNumber in: query required: false description: Contact phone, digits with optional leading +. schema: type: string example: '919876543210' - name: name in: query required: false description: Display name. Defaults to phoneNumber on create. schema: type: string - name: email in: query required: false description: Contact email. schema: type: string example: john@acme.com - name: profilePictureUrl in: query required: false description: Avatar URL. schema: type: string - name: customFieldsData in: query required: false description: >- Map of custom field values, or "k:v,k:v" string. Keys resolve case-insensitively. schema: type: object additionalProperties: true example: {} - name: labelNames in: query required: false description: Labels to set. Accepts array, comma string, or label alias. schema: type: array items: {} example: [] requestBody: required: true content: application/json: schema: type: object required: - phoneNumber properties: channelId: type: string description: >- Channel id. Auto-selects the first active channel when omitted. example: ch_123 phoneNumber: type: string description: Contact phone, digits with optional leading +. example: '919876543210' name: type: string description: Display name. Defaults to phoneNumber on create. email: type: string description: Contact email. example: john@acme.com profilePictureUrl: type: string description: Avatar URL. customFieldsData: type: object additionalProperties: true description: >- Map of custom field values, or "k:v,k:v" string. Keys resolve case-insensitively. example: {} labelNames: type: array items: {} description: Labels to set. Accepts array, comma string, or label alias. example: [] example: channelId: ch_123 phoneNumber: '919876543210' name: John Doe email: john@example.com responses: '200': description: 'Success. Envelope: { success:true, data, message? }.' content: application/json: schema: type: object required: - success properties: success: type: boolean example: true data: {} message: type: string pagination: type: object total: type: number example: success: true data: id: ct_1 channelId: ch_123 phone: '919876543210' name: John Doe message: Contact created successfully '400': description: >- Missing/invalid parameters. Body has success:false plus error and message. content: application/json: schema: type: object required: - success - error properties: success: type: boolean example: false error: type: string message: type: string '401': description: >- Missing or invalid API key (or session expired for session endpoints). content: application/json: schema: type: object required: - success - error properties: success: type: boolean example: false error: type: string message: type: string '403': description: >- Authenticated but not authorized — wrong permissions or cross-tenant resource. content: application/json: schema: type: object required: - success - error properties: success: type: boolean example: false error: type: string message: type: string '429': description: >- Rate limited. Retry after the Retry-After seconds; see RateLimit-* headers. content: application/json: schema: type: object required: - success - error properties: success: type: boolean example: false error: type: string message: type: string '500': description: >- Unexpected server error. Body has success:false plus error and message. content: application/json: schema: type: object required: - success - error properties: success: type: boolean example: false error: type: string message: type: string security: - apiKeyHeader: [] - bearerAuth: [] components: securitySchemes: apiKeyHeader: type: apiKey in: header name: X-API-Key description: Preferred. API key value directly. bearerAuth: type: http scheme: bearer description: Alternative. API key as the bearer token. ````