> ## Documentation Index > Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt > Use this file to discover all available pages before exploring further. # Create / Update Users > API to upsert (create if not exists, update if exists) user profile using a `distinct_id`. ## OpenAPI ````yaml POST /v1/user/{distinct_id}/ openapi: 3.1.1 info: title: SuprSend API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] paths: /v1/user/{distinct_id}/: post: summary: Create / Update Users description: >- API to upsert (create if not exists, update if exists) user profile using a `distinct_id`. operationId: create-update-users parameters: - name: distinct_id in: path description: Unique identifier of the user in your system schema: type: string required: true requestBody: content: application/json: example: $email: - jsmith@example.com $sms: - '+1234567890' $whatsapp: - '+1234567890' $inbox: - 4nlPk4XXLcDxxxHQ70xx2Cx24 $webpush: - token: webpush_token_abc123 endpoint: https://fcm.googleapis.com/fcm/send/abc123 keys: p256dh: BNJxwH... auth: tBH... $androidpush: - android_push_token_xyz987 $iospush: - ios_push_token_lmn456 $slack: - user_id: U01ABCDE2F3 team_id: T1234567890 access_token: xoxb-... $ms_teams: - user_id: teams_user_id_12345 tenant_id: tenant_12345 conversation_id: conversation_12345 $timezone: America/New_York $locale: en_GB custom_key: custom_value schema: type: object properties: $email: type: array items: type: string format: email description: >- List of email addresses. You can add other channels in the same format by replacing `$email` with the respective channel keys. Supported keys- `$email`, `$sms`, `$whatsapp`, `$inbox`, `$webpush`, `$androidpush`, `$iospush`, `$slack`, `$ms_teams`. $sms: type: array items: type: string description: List of phone numbers for SMS $whatsapp: type: array items: type: string description: List of phone numbers for WhatsApp $inbox: type: array items: type: string description: List of inbox identifiers $androidpush: type: array items: type: string description: List of Android Push tokens $iospush: type: array items: type: string description: List of iOS Push tokens $slack: type: array description: Slack channel configuration items: oneOf: - type: object title: Slack using email required: - email - access_token properties: email: type: string format: email description: User email address example: user@example.com access_token: type: string description: Slack bot access token example: xoxb-XXXXXXXX - type: object title: Slack using member ID required: - user_id - access_token properties: user_id: type: string description: Slack user ID (U/WXXXXXXXX format) example: U/WXXXXXXXX access_token: type: string description: Slack bot access token example: xoxb-XXXXXX - type: object title: Slack using channel required: - channel - access_token properties: channel: type: string description: Slack channel ID (CXXXXXXXX format) example: CXXXXXXXX access_token: type: string description: Slack bot access token example: xoxb-XXXXXX - type: object title: Slack using incoming webhook required: - incoming_webhook properties: incoming_webhook: type: object required: - url properties: url: type: string format: uri description: Slack incoming webhook URL example: >- https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX $ms_teams: type: array description: Microsoft Teams channel configuration items: oneOf: - type: object title: MS Teams using conversation ID required: - tenant_id - service_url - conversation_id properties: tenant_id: type: string description: Microsoft Teams tenant ID example: c1981ab2-9aaf-xxxx-xxxx service_url: type: string format: uri description: Microsoft Teams service URL example: https://smba.trafficmanager.net/amer conversation_id: type: string description: Microsoft Teams conversation ID example: 19:c1524d7c-a06f-456f-8abe-xxxx - type: object title: MS Teams using user ID required: - tenant_id - service_url - user_id properties: tenant_id: type: string description: Microsoft Teams tenant ID example: c1981ab2-9aaf-xxxx-xxxx service_url: type: string format: uri description: Microsoft Teams service URL example: https://smba.trafficmanager.net/amer user_id: type: string description: Microsoft Teams user ID example: 29:1nsLcmJ2RKtYH6Cxxxx-xxxx - type: object title: MS Teams using incoming webhook required: - incoming_webhook properties: incoming_webhook: type: object required: - url properties: url: type: string format: uri description: Microsoft Teams incoming webhook URL example: >- https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX $timezone: type: string description: >- User's timezone in [IANA format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) example: America/New_York $locale: type: string description: >- User's locale for [translating](https://suprsend.com/docs/translations) template content in SuprSend. example: en_GB additionalProperties: type: string description: Add any additional property in key-value pair example: val responses: '201': description: '201' content: application/json: examples: Result: value: distinct_id: _distinct_id_ properties: $locale: en_GB $timezone: America/New_York created_at: '2025-04-04T21:37:36.712496+00:00' updated_at: '2025-04-04T21:37:36.743167+00:00' $email: - value: john@example.com status: active perma_status: active $inbox: - value: 4nlPk4t4kurG5kChOELB8Q1LcDI9DHzHQ70st2E2C24 id_provider: suprsend status: active perma_status: active $sms: - value: '+1234567890' status: active perma_status: active $slack: - value: email_id: user@example.com access_token: xoxb-... status: active perma_status: active $ms_teams: - value: user_id: teams_user_id_12345 tenant_id: tenant_12345 service_url: https://smba.trafficmanager.net/amer status: active perma_status: active schema: type: object properties: distinct_id: type: string example: _distinct_id_ properties: type: object description: >- all user properties in key-value pair. SuprSend reserved properties start with $ created_at: type: string format: date-time example: '2025-04-04T09:55:12.397Z' updated_at: type: string format: date-time example: '2025-04-04T09:55:12.422Z' $: type: array items: type: object properties: value: type: string description: channel value status: type: string example: active perma_status: type: string description: >- active/disabled. Perma_status is marked disabled in case of hard bounce on the channel. '400': description: '400' content: application/json: examples: Result: value: code: 400 message: invalid_request_error schema: type: object properties: code: type: integer description: HTTP status code indicating the error. message: type: string description: Description of the error type. deprecated: false security: - BearerAuth: [] x-codeSamples: - lang: cURL source: | curl -X POST "https://hub.suprsend.com/v1/user/user123/" \ --header 'Authorization: Bearer __YOUR_API_KEY__' \ --header 'Content-Type: application/json' \ --data '{ "$email": ["user@example.com"], "$sms": ["+1234567890"], "$slack": [{ "email_id": "user@example.com", "access_token": "xoxb-..." }], "$ms_teams": [{ "user_id": "teams_user_id_12345", "tenant_id": "tenant_12345", "service_url": "https://smba.trafficmanager.net/amer" }] }' components: securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: >- Bearer authentication header of the form `Bearer `, where is your auth token. BearerAuth: type: http scheme: bearer bearerFormat: API_Key description: >- Pass as `Bearer `. Get API Key from SuprSend dashboard Developers -> API Keys section. ```` Built with [Mintlify](https://mintlify.com).