---
title: "Register a new user"
method: POST
path: "/v1/users"
tags: ["Users"]
---

# Register a new user

`POST /v1/users`

## Request

- Base URL: `https://identity-api.paymongo.com`
- URL: `https://identity-api.paymongo.com/v1/users`
- Auth: none required

Creates a new user. Request body is JSON:API enveloped (`data.attributes`).
Signup path is determined by attributes:
- token present              → assignee signup (from invitation)
- linking_request_id present → linked-invite signup (accounts-api creates the child org)
- neither                    → account-owner signup (creates a new org)
When supplied, contact_number must be an E.164 number with any country code (e.g. +639171234567) — anything else returns 422.

## Request body

- UserSignupRequestEnvelopeDTO
  - `data` object
    - `attributes` UserSignupRequestDTO
      - `accelerator_program_code` string
      - `accepted_marketing` boolean
      - `accepted_terms` boolean
      - `affiliate_partner` string
      - `contact_number` string: ContactNumber is optional. The assignee-invite signup form collects it as "Mobile number"; the self-serve account-owner form does not. When supplied, it must be an E.164 number with any country code (e.g. +639171234567) — enforced at the use-case level so every signup path gets the same constraint.
      - `department` 'customer_service_and_support' | 'finance_and_accounting' | 'it_developer' | 'operations' | 'owner_management' | 'sales_and_marketing': Must be one of the values GET /v1/departments serves. Required on the assignee-invite path, optional elsewhere.
      - `email` string, required
      - `first_name` string, required
      - `last_name` string, required
      - `linking_request_id` string: Linked-invite signup: id of the accounts-api linking request issued by the inviting parent merchant. accounts-api validates and creates the child org; identity-api attaches the user once it returns.
      - `password` string, required
      - `password_confirmation` string, required
      - `referral_code` string: Account-owner signup: optional referral code. Mutually exclusive with linking_request_id since the linked-invite path doesn't create a top-level org and so cannot apply referral credit.
      - `sales_invitation_token` string: Sales-invite signup: token from sales-api account invitation. Mutually exclusive with linking_request_id and referral_code. The organization already exists — identity-api validates via sales-api, creates the owner user, then marks the invitation used.
      - `token` string: Assignee signup
      - `utm_campaign` string
      - `utm_content` string
      - `utm_medium` string
      - `utm_source` string
      - `utm_term` string
      - `utm_type` string
      - `visitor_id` string

## Response `201`

Created

- object: Standard response containing data and its metadata if any
  - `data` object
    - `attributes` UserSignupResponseDTO
      - `email` string
      - `email_confirmed` boolean
      - `first_name` string
      - `last_name` string
    - `id` string
    - `type` string
  - `has_more` boolean

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `410`: Gone
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/paymongo/apis/identity.md) - [All operations](https://skmtc.dev/paymongo/apis/identity/llms.txt) - [OpenAPI document](https://skmtc.dev/paymongo/apis/identity/revisions/cc3056164874?raw)