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

# Add Name to a User List

```http POST theme={"system"}
POST https://api.nameshouts.com/api/v2.0/user/user-list/add-name-to-list?name=John-Abrams2&language=English&user_list_id=82076&email=test@test2.com
```

This endpoint adds a specific name to a list.

The parameters required are as follows:

| **Parameters** | **Description** |
| - | - |
| name | The name to be added. Please note that for multiple names, the format has to be "**John-Smith**" and not "**John Smith**". |
| language | The language of origin. If not know, you can use **English** as the default. |
| user\_list\_id | The unique identifier for the list |
| email | Email is an **optional** parameter. This will be the email of the person that the name belongs to. |

If the name is successfully added to the list, the response object will indicate that by displaying this message. `"`**`Name added to list.`**`"`

If the name is missing from the database, the name will be automatically requested to NameShouts. **`"Name not on database. Missing Name information sent to NameShouts."`**

If the name already exists, then the response object will return the following message. **`"Name already in list"`**

The examples below show the response for three scenarios.

**Note:** You can add the same name "**John Smith**" for **two unique emails**. You will not be able to add the same name with the same email more than once on the list.

## Authorization

| Bearer Token | |
| - | - |
| Token | `<token>` |

## Params

**name** `string`

The name to be added to the list. Please note that spaces between names should be delimited by hypens(-).

Example: `John-Abrams2`

**language** `string`

The language of origin for the name. If the language of origin is not known, please use "English" as a default.

Example: `English`

**user\_list\_id** `string`

The unique identifier for the list

Example: `82076`

**email** `string`

Email is an optional parameter. This is the email of the person that the name belongs to.

Example: `test@test2.com`

## Examples

### Added to List.

**Example Request**

```bash curl theme={"system"}
curl --location -g --request POST '{{base_url}}/api/v2.0/user/user-list/add-name-to-list?name=John-Smith&language=English&user_list_id=12&email=test4%40test.com'
```

**Example Response** · `200 OK`

```json Body theme={"system"}
"Name added to list."
```

**Headers (9)**

| Key | Value |
| - | - |
| Server | nginx/1.23.3 |
| Content-Type | application/json |
| Transfer-Encoding | chunked |
| Connection | keep-alive |
| Vary | Accept-Encoding |
| X-Powered-By | PHP/7.4.33 |
| Cache-Control | no-cache, private |
| Date | Wed, 20 Sep 2023 05:56:35 GMT |
| Content-Encoding | gzip |

### Missing from Database.

**Example Request**

```bash curl theme={"system"}
curl --location -g --request POST '{{base_url}}/api/v2.0/user/user-list/add-name-to-list?name=Johnr-Smith&language=English&user_list_id=12&email=test4%40test.com'
```

**Example Response** · `200 OK`

```json Body theme={"system"}
[
    "Name not on database. Missing Name information sent to NameShouts."
]
```

**Headers (9)**

| Key | Value |
| - | - |
| Server | nginx/1.23.3 |
| Content-Type | application/json |
| Transfer-Encoding | chunked |
| Connection | keep-alive |
| Vary | Accept-Encoding |
| X-Powered-By | PHP/7.4.33 |
| Cache-Control | no-cache, private |
| Date | Wed, 20 Sep 2023 05:57:03 GMT |
| Content-Encoding | gzip |

### Already on List.

**Example Request**

```bash curl theme={"system"}
curl --location -g --request POST '{{base_url}}/api/v2.0/user/user-list/add-name-to-list?name=John-Smith&language=English&user_list_id=12&email=test4%40test.com'
```

**Example Response** · `400 Bad Request`

```json Body theme={"system"}
"Name already in list"
```

**Headers (7)**

| Key | Value |
| - | - |
| Server | nginx/1.23.3 |
| Content-Type | application/json |
| Transfer-Encoding | chunked |
| Connection | keep-alive |
| X-Powered-By | PHP/7.4.33 |
| Cache-Control | no-cache, private |
| Date | Wed, 20 Sep 2023 06:52:48 GMT |

```bash cURL theme={"system"}
curl --location --request POST 'https://api.nameshouts.com/api/v2.0/user/user-list/add-name-to-list?name=John-Abrams2&language=English&user_list_id=82076&email=test%40test2.com' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

```json Added to List. (200) theme={"system"}
"Name added to list."
```

```json Missing from Database. (200) theme={"system"}
[
    "Name not on database. Missing Name information sent to NameShouts."
]
```

```json Already on List. (400) theme={"system"}
"Name already in list"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.