---
description: >-
  An alternative to our SDK - for submitting custom attributes to new or
  existing customers.
---

# API

### What can you use the Mava API for?

1. Custom Attributes: You can use the Mava API to push user attributes to Mava via the identify endpoint. This offers similar functionality to the web chat [SDK](../getting-started/integration-setup/web-chat-setup/automatically-capture-custom-user-data-sdk) but can be used with all integration options and enables you to push data from third-party systems, such as your database, into Mava. &#x20;
2. Status Updates: You can use the API to update ticket statuses, for example to close them.&#x20;
3. Ticket Updates: You can use the API to update tickets, for example adding a tag or category.&#x20;
4. Private Notes:  You can use the API to add private notes to tickets.
5. Messages: sending messages via API is coming soon.&#x20;
6. Creating Tickets: creating tickets is coming soon\


We're expanding our API so if you're looking to build more with the Mava API please send us a message or [book a feedback call](https://calendly.com/richard-mava/30min).

###

### Getting Started

Head over to the [API section](https://dashboard.mava.app/dashboard/admin/api/keys) within the Mava dashboard and create an API key.&#x20;



_Please note:  If you send no customer ID, a customer will be created for you and a new customer ID sent back which should be stored and used for subsequent calls to update that same customer._

\
**CURL**

```bash
curl -X POST https://gateway.mava.app/api/identify \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "",
    "mavaCustomerId": "",
    "customAttributes": [
      {
        "label": "exampleLabel",
        "value": "exampleValue"
      }
    ]
  }'
```

**NodeJS**

```javascript
fetch('https://gateway.mava.app/api/identify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-token': 'YOUR_AUTH_TOKEN_HERE'
  },
  body: JSON.stringify({
    emailAddress: '', 
    mavaCustomerId: '',
    customAttributes: [
      {
        label: 'exampleLabel',
        value: 'exampleValue'
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch((error) => console.error('Error:', error));
```

**Schema**

```
{
  "type": "object",
  "properties": {
    "emailAddress": {
      "type": "string"
    },
    "plaformUserId": {
      "type": "string"
    },
    "mavaCustomerId": {
      "type": "string"
    },
    "customAttributes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": ["label", "value"]
      }
    }
  }
}
```

##

## API Endpoints

### 1. Get Categories

Retrieves a list of all active categories for the authenticated client.

#### Endpoint

```
GET /api/categories
```

#### Authentication

* Requires API token authentication
* Subject to rate limiting

#### Response

**Success (200 OK)**

```json
{
  "categories": [
    {
      "_id": "string",
      "name": "string"
    }
  ]
}
```

**Error (500 Internal Server Error)**

```json
{
  "error": "Internal server error"
}
```

### 2. Update Ticket

Updates a ticket's status, priority, and/or category.

#### Endpoint

```
PUT /api/ticket
```

#### Authentication

* Requires API token authentication
* Subject to rate limiting

#### Request Body

| Field      | Type   | Required | Description                         |
| ---------- | ------ | -------- | ----------------------------------- |
| ticketId   | string | Yes      | The unique identifier of the ticket |
| status     | string | No       | New ticket status                   |
| priority   | number | No       | New priority level                  |
| categoryId | string | No       | ID of the category to assign        |

#### Valid Values

* **Status**: `"Open"`, `"Resolved"`, `"Pending"`, `"Waiting"`
* **Priority**: `1`, `2`, `3`
* **CategoryId**: Must be a valid category ID from GET /categories

#### Response

**Success (200 OK)**

```json
{
  "message": "Ticket updated"
}
```

**Error Responses**

**Ticket not found (400)**

```json
{
  "error": "Ticket not found"
}
```

**Invalid category (400)**

```json
{
  "error": "Category not found"
}
```

**Invalid status/priority (400)**

```json
{
  "error": "Invalid status or priority"
}
```

**Server error (500)**

```json
{
  "error": "Internal server error"
}
```

#### Behavior

* Each change (status, priority, category) creates an audit log message
* Changes are only made if the new value differs from the current value
* Category must be active (not archived) and belong to the client

