# Users

## Create a conversation user

> Creates a new conversation user using either an email or phoneNumber.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"CreateUserWithPhoneNumberBodyDTO":{"type":"object","properties":{"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkUserId":{"type":"string","description":"User fkUserId"},"customData":{"type":"object","description":"Conversation user custom data"},"skipPhoneNumberValidation":{"type":"boolean","description":"Skip phone number validation"},"skipEmailValidation":{"type":"boolean","description":"Skip email validation"},"phoneNumber":{"type":"string","description":"User phone number"},"email":{"type":"string","description":"User email"},"fkId":{"type":"string","description":"User fkId"}},"required":["firstName","lastName","phoneNumber"]},"CreateUserWithEmailBodyDTO":{"type":"object","properties":{"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkUserId":{"type":"string","description":"User fkUserId"},"customData":{"type":"object","description":"Conversation user custom data"},"skipPhoneNumberValidation":{"type":"boolean","description":"Skip phone number validation"},"skipEmailValidation":{"type":"boolean","description":"Skip email validation"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"fkId":{"type":"string","description":"User fkId"}},"required":["firstName","lastName","email"]},"CreateUserWithFkIdBodyDTO":{"type":"object","properties":{"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkUserId":{"type":"string","description":"User fkUserId"},"customData":{"type":"object","description":"Conversation user custom data"},"skipPhoneNumberValidation":{"type":"boolean","description":"Skip phone number validation"},"skipEmailValidation":{"type":"boolean","description":"Skip email validation"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"fkId":{"type":"string","description":"User fkId"}},"required":["firstName","lastName","fkId"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"BadRequestErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"name":{"type":"object","default":"BAD_REQUEST"},"message":{"type":"string","default":"INVALID_REQUEST"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/users":{"post":{"description":"Creates a new conversation user using either an email or phoneNumber.","operationId":"ExternalApiUsersController_createConversationUser","parameters":[],"requestBody":{"required":true,"description":"Provide the user details to create.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateUserWithPhoneNumberBodyDTO"},{"$ref":"#/components/schemas/CreateUserWithEmailBodyDTO"},{"$ref":"#/components/schemas/CreateUserWithFkIdBodyDTO"}]}}}},"responses":{"201":{"description":"Successfully created a new conversation user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}}}},"400":{"description":"User already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create a conversation user","tags":["Users","Agent API Key"]}}}}
```

## Find user by contact information

> Retrieves a user by their email, phone number or fkId, along with their conversation IDs for the current agent.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"SearchConversationUserByContactsResponseDTO":{"type":"object","properties":{"user":{"description":"User info","allOf":[{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}]},"conversationIds":{"description":"Conversation ids","type":"array","items":{"type":"string"}}},"required":["user","conversationIds"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"BadRequestErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"name":{"type":"object","default":"BAD_REQUEST"},"message":{"type":"string","default":"INVALID_REQUEST"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/users/search":{"get":{"description":"Retrieves a user by their email, phone number or fkId, along with their conversation IDs for the current agent.","operationId":"ExternalApiUsersController_findUserByContactInfo","parameters":[{"name":"email","required":false,"in":"query","description":"User email","schema":{"type":"string"}},{"name":"phoneNumber","required":false,"in":"query","description":"User phone number","schema":{"type":"string"}},{"name":"fkId","required":false,"in":"query","description":"User fkId","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the user and conversation ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchConversationUserByContactsResponseDTO"}}}},"400":{"description":"Invalid parameters provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"User not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Find user by contact information","tags":["Users","Agent API Key"]}}}}
```

## Get conversation user by ID

> Retrieves a conversation user by their unique identifier.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"}},"required":["id","firstName","lastName"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/users/{id}":{"get":{"description":"Retrieves a conversation user by their unique identifier.","operationId":"ExternalApiUsersController_getConversationUser","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the conversation user.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the conversation user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApiUserResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"User not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get conversation user by ID","tags":["Users","Agent API Key"]}}}}
```

## Delete conversation user by ID

> Delete a conversation user by their unique identifier.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/users/{id}":{"delete":{"description":"Delete a conversation user by their unique identifier.","operationId":"ExternalApiUsersController_deleteConversationUserById","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the conversation user.","schema":{"type":"string"}}],"responses":{"204":{"description":"Successfully delete the conversation user."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Conversation user not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete conversation user by ID","tags":["Users","Agent API Key"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.raiaai.com/api-reference/users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.