> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/azfar-imtiaz/PayPulse-Cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign up

> Create a new PayPulse user account.

## Request body

<ParamField body="email" type="string" required>
  The user's email address. Must be unique across all accounts.
</ParamField>

<ParamField body="name" type="string" required>
  The user's display name.
</ParamField>

<ParamField body="password" type="string" required>
  The user's password. Stored as a bcrypt hash.
</ParamField>

## Response

<ResponseField name="message" type="string">
  A human-readable confirmation message. Example: `"Signup successful!"`
</ResponseField>

<ResponseField name="code" type="number">
  HTTP status code. `201` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="username" type="string">
      The display name provided during signup.
    </ResponseField>

    <ResponseField name="access_token" type="string">
      A signed HS256 JWT token valid for 1 hour. Use this as a Bearer token in subsequent requests.
    </ResponseField>

    <ResponseField name="token_type" type="string">
      Always `"Bearer"`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Error code              | Description                                                           |
| ------ | ----------------------- | --------------------------------------------------------------------- |
| `400`  | `INVALID_CREDENTIALS`   | The provided credentials are malformed or fail validation.            |
| `400`  | `INVALID_JSON`          | The request body is not valid JSON.                                   |
| `400`  | `MISSING_FIELDS`        | One or more required fields (`email`, `name`, `password`) are absent. |
| `403`  | `USER_ALREADY_EXISTS`   | An account with the given email address already exists.               |
| `502`  | `DEPENDENCY_FAILURE`    | A downstream dependency (DynamoDB or S3) returned an error.           |
| `500`  | `INTERNAL_SERVER_ERROR` | An unexpected server-side error occurred.                             |

Error responses follow this structure:

```json theme={null}
{
  "error": {
    "code": "USER_ALREADY_EXISTS",
    "message": "User with email 'user@example.com' already exists."
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.paypulse.io/v1/auth/signup \
    --header 'Content-Type: application/json' \
    --data '{
      "email": "jane@example.com",
      "name": "Jane Doe",
      "password": "s3cur3P@ssword!"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "message": "Signup successful!",
    "code": 201,
    "data": {
      "username": "Jane Doe",
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "USER_ALREADY_EXISTS",
      "message": "User with email 'jane@example.com' already exists."
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "MISSING_FIELDS",
      "message": "Missing key in request body: 'password'"
    }
  }
  ```
</ResponseExample>