> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nymble Commerce Users API — Manage Accounts and Associations

> API reference for managing user accounts in Nymble Commerce, including listing users, updating profiles, and managing access across organizations.

The Users endpoints allow you to view and manage user accounts within your organization. You can create new users, look up profile information, check whether an account exists, and retrieve the customer associations and organization memberships tied to a specific user.

<Note>
  Most endpoints in this section require an **Admin** policy. The sole exception is `GET /api/users/profile`, which requires a **Customer**-scoped token, and `GET /api/users/exists`, which is public and requires no authentication at all.
</Note>

***

## POST /api/users

Create a new user account and add them to your organization. If the email address is already registered on the platform, the existing account is reused and only the organization membership is added.

<Warning>
  **Requires Admin role.** Calls from tokens without the `Admin` policy return `403 Forbidden`.
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="FirstName" type="string" required>
  The user's first name.

  Example: `"Jane"`
</ParamField>

<ParamField body="LastName" type="string" required>
  The user's last name.

  Example: `"Smith"`
</ParamField>

<ParamField body="Email" type="string" required>
  The user's email address. Used as the login identifier. Must be unique across the platform.

  Example: `"jane.smith@example.com"`
</ParamField>

<ParamField body="Password" type="string">
  An initial password for the user. Ignored if the email is already registered on the platform — in that case the user keeps their current credentials.

  Example: `"SecurePass123!"`
</ParamField>

<ParamField body="PhoneNumber" type="string">
  The user's phone number.

  Example: `"561-555-1212"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.achievemomentum.com/api/users \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "FirstName": "Jane",
    "LastName": "Smith",
    "Email": "jane.smith@example.com",
    "Password": "SecurePass123!",
    "PhoneNumber": "561-555-1212"
  }'
```

### Response fields

<ResponseField name="FirstName" type="string">
  The created user's first name.
</ResponseField>

<ResponseField name="LastName" type="string">
  The created user's last name.
</ResponseField>

<ResponseField name="Email" type="string">
  The created user's email address.
</ResponseField>

<ResponseField name="PhoneNumber" type="string">
  The created user's phone number.
</ResponseField>

### Example response

```json theme={null}
{
  "FirstName": "Jane",
  "LastName": "Smith",
  "Email": "jane.smith@example.com",
  "PhoneNumber": "561-555-1212"
}
```

### Error responses

| Status                      | Description                               |
| --------------------------- | ----------------------------------------- |
| `400 Bad Request`           | A required field is missing or invalid.   |
| `403 Forbidden`             | Your token does not carry the Admin role. |
| `500 Internal Server Error` | An unexpected error occurred.             |

***

## GET /api/users/profile

Returns the profile of the currently authenticated user. The user ID and organization ID are read from the JWT claims — you do not pass them as parameters.

<Warning>
  **Requires Customer role.** Calls from tokens without a Customer policy return `403 Forbidden`.
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_access_token}
```

### Example request

```bash cURL theme={null}
curl https://api.achievemomentum.com/api/users/profile \
  -H "Authorization: Bearer {your_access_token}"
```

### Response fields

<ResponseField name="FirstName" type="string">
  The authenticated user's first name.
</ResponseField>

<ResponseField name="LastName" type="string">
  The authenticated user's last name.
</ResponseField>

<ResponseField name="Email" type="string">
  The authenticated user's preferred email address.
</ResponseField>

<ResponseField name="PhoneNumber" type="string">
  The authenticated user's phone number.
</ResponseField>

### Example response

```json theme={null}
{
  "FirstName": "Jane",
  "LastName": "Smith",
  "Email": "jane.smith@example.com",
  "PhoneNumber": "561-555-1212"
}
```

### Error responses

| Status             | Description                                    |
| ------------------ | ---------------------------------------------- |
| `404 Not Found`    | No user record exists for the ID in the token. |
| `400 Bad Request`  | The request is malformed.                      |
| `401 Unauthorized` | The bearer token is missing or expired.        |

***

## GET /api/users/exists

Check whether a user account exists for a given email address. This endpoint is **public** — it does not require authentication.

<Note>
  This endpoint is rate limited to 10 requests per minute per IP address.
</Note>

### Query parameters

<ParamField query="Email" type="string" required>
  The email address to look up.

  Example: `john@example.com`
</ParamField>

### Example request

```bash cURL theme={null}
curl "https://api.achievemomentum.com/api/users/exists?Email=john%40example.com"
```

### Response fields

<ResponseField name="UserExists" type="boolean">
  `true` if an account with the given email address exists on the platform; `false` otherwise.
</ResponseField>

### Example response

```json theme={null}
{
  "UserExists": true
}
```

### Error responses

| Status            | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `400 Bad Request` | The `Email` parameter is missing or not a valid email format. |

***

## GET /api/users/organizations

Returns the list of organizations the currently authenticated user belongs to. The user ID and email are read from the JWT claims — you do not pass them as parameters.

<Warning>
  **Requires Admin role.** Calls from tokens without the `Admin` policy return `403 Forbidden`.
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Example request

```bash cURL theme={null}
curl https://api.achievemomentum.com/api/users/organizations \
  -H "Authorization: Bearer {your_admin_access_token}"
```

### Response fields

<ResponseField name="Organizations" type="array">
  An array of organization objects the user belongs to.

  <Expandable title="Organization object">
    <ResponseField name="OrganizationId" type="string">
      The unique Nymble Commerce organization ID.
    </ResponseField>

    <ResponseField name="Name" type="string">
      The organization's display name.
    </ResponseField>

    <ResponseField name="Slug" type="string">
      The organization's URL-friendly identifier.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "Organizations": [
    {
      "OrganizationId": "6d24ab9faf9e034e881fcd97",
      "Name": "Acme Corp",
      "Slug": "acme-corp"
    }
  ]
}
```

### Error responses

| Status            | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| `400 Bad Request` | The user cannot be found based on your token's identity claims. |
| `403 Forbidden`   | Your token does not carry the Admin role.                       |

***

## GET /api/users/customer-association

Retrieve the customer record linked to a specific user within your organization. The organization is derived from your JWT claims. Use this to find which customer account a user is associated with.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Query parameters

<ParamField query="UserId" type="string" required>
  The user ID of the user to look up.

  Example: `"kp_abc123def456"`
</ParamField>

### Example request

```bash cURL theme={null}
curl "https://api.achievemomentum.com/api/users/customer-association?UserId=kp_abc123def456" \
  -H "Authorization: Bearer {your_admin_access_token}"
```

### Response fields

<ResponseField name="UserId" type="string">
  The user ID.
</ResponseField>

<ResponseField name="CustomerNumber" type="string">
  The customer account number linked to this user.
</ResponseField>

<ResponseField name="OrganizationId" type="string">
  The organization this association belongs to.
</ResponseField>

### Example response

```json theme={null}
{
  "UserId": "kp_abc123def456",
  "CustomerNumber": "C-10042",
  "OrganizationId": "6d24ab9faf9e034e881fcd97"
}
```

### Error responses

| Status            | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `404 Not Found`   | No customer association exists for this user in your organization. |
| `400 Bad Request` | `UserId` is missing.                                               |
| `403 Forbidden`   | Your token does not carry the Admin role.                          |

***

## GET /api/users/customer-associations

Returns all customer associations for a given user across all organizations. Useful when a single user account is linked to multiple customer records.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Query parameters

<ParamField query="UserId" type="string" required>
  The user ID to retrieve associations for.

  Example: `"kp_abc123def456"`
</ParamField>

### Example request

```bash cURL theme={null}
curl "https://api.achievemomentum.com/api/users/customer-associations?UserId=kp_abc123def456" \
  -H "Authorization: Bearer {your_admin_access_token}"
```

### Response

Returns an array of customer association objects.

<ResponseField name="[]" type="array">
  A flat array of `UserCustomer` association objects.

  <Expandable title="UserCustomer object">
    <ResponseField name="UserId" type="string">
      The user ID.
    </ResponseField>

    <ResponseField name="CustomerNumber" type="string">
      The customer account number linked to this user.
    </ResponseField>

    <ResponseField name="OrganizationId" type="string">
      The organization this association belongs to.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
[
  {
    "UserId": "kp_abc123def456",
    "CustomerNumber": "C-10042",
    "OrganizationId": "6d24ab9faf9e034e881fcd97"
  },
  {
    "UserId": "kp_abc123def456",
    "CustomerNumber": "C-20099",
    "OrganizationId": "7e35bc0abf0f145f992gde08"
  }
]
```

### Error responses

| Status            | Description                               |
| ----------------- | ----------------------------------------- |
| `400 Bad Request` | `UserId` is missing or invalid.           |
| `403 Forbidden`   | Your token does not carry the Admin role. |