> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get an end user
> Fetch a single end-user record by its ID, or a 404 NOT_FOUND when no record matches.
Returns one end-user record by ID.
Requires a key with the **End-users** permission. See [API authentication](/docs/developer/authentication).
The `_id` of the record, as returned by list or create.
## Response
Returns the [end-user record](/docs/developer/api/end-users#the-end-user-record), or `404` with code `NOT_FOUND`.
```json 200 theme={null}
{
"_id": "eu_123",
"name": "Ada Point",
"email": "ada@example.com",
"origin": "manual",
"tags": ["vip"],
"createdAt": 1753747200000,
"lastSeenAt": 1753747200000
}
```
## Errors
| Status | Code | Cause |
| ------ | -------------- | -------------------------------------- |
| `400` | `INVALID_URL` | A bad path |
| `401` | `UNAUTHORIZED` | Missing, invalid, or revoked key |
| `403` | `FORBIDDEN` | Key lacks the **End-users** permission |
| `404` | `NOT_FOUND` | No record matches the ID |
## OpenAPI
````yaml api-reference/openapi.json GET /api/endusers/{endUserId}
openapi: 3.1.0
info:
title: Tars API
version: 3.0.0
description: >-
Public REST API for Tars agents: start conversations at trigger gambits,
send channel messages, manage end users, and drive webhook campaigns.
servers:
- url: https://us.api.hellotars.com
description: United States
- url: https://eu.api.hellotars.com
description: European Union
- url: https://in.api.hellotars.com
description: India
- url: https://qa.api.hellotars.com
description: Qatar
security:
- bearerAuth: []
tags:
- name: Triggers
description: Start conversations at trigger gambits
- name: Channels
description: Outbound channel message sends
- name: End users
description: End-user record management
- name: Campaigns
description: Webhook campaign sends and validation
paths:
/api/endusers/{endUserId}:
parameters:
- name: endUserId
in: path
required: true
description: The end-user record ID
schema:
type: string
get:
tags:
- End users
summary: Get an end user
operationId: getEndUser
responses:
'200':
description: The end-user record
content:
application/json:
schema:
$ref: '#/components/schemas/EndUser'
'400':
description: Path does not match /api/endusers/{endUserId} (INVALID_URL)
content:
application/json:
schema:
$ref: '#/components/schemas/EndUserError'
'401':
description: Missing, invalid, or revoked API key (UNAUTHORIZED)
content:
application/json:
schema:
$ref: '#/components/schemas/EndUserError'
'403':
description: Key lacks the endusers scope (FORBIDDEN)
content:
application/json:
schema:
$ref: '#/components/schemas/EndUserError'
'404':
description: No record matches the ID (NOT_FOUND)
content:
application/json:
schema:
$ref: '#/components/schemas/EndUserError'
components:
schemas:
EndUser:
type: object
description: An end-user record in your organization.
properties:
_id:
type: string
description: The end-user record ID. Pass it to the single-record endpoints.
name:
type: string
description: Display name.
email:
type: string
description: Email address, normalized by Tars.
phone:
type: string
description: Phone number in international format.
tags:
type: array
items:
type: string
description: Free-form tags applied to this record.
origin:
type: string
enum:
- inbound
- imported
- manual
description: >-
How the record was created. inbound came from a conversation,
imported came from a file import, and manual was created by hand or
over this API.
channelIdentifiers:
$ref: '#/components/schemas/ChannelIdentifiers'
consent:
type: object
description: >-
Consent for each channel, keyed by channel name such as web or
whatsapp. Absent when no consent has been recorded.
additionalProperties:
$ref: '#/components/schemas/ChannelConsent'
createdAt:
type: number
description: When the record was created, in milliseconds since epoch.
lastSeenAt:
type: number
description: When the end user was last active, in milliseconds since epoch.
required:
- _id
- origin
- createdAt
- lastSeenAt
EndUserError:
type: object
description: An error from the end-user endpoints.
properties:
error:
type: string
description: A sentence describing what went wrong.
code:
type: string
description: >-
A stable machine-readable code, for example DUPLICATE_ENDUSER or
INVALID_ORIGIN.
details:
type: object
description: >-
Reserved for extra error context. The end-user endpoints do not
currently return it.
required:
- error
- code
ChannelIdentifiers:
type: object
description: >-
Where Tars can reach this end user on each channel. Every field is
optional, and only the channels Tars has seen are present.
properties:
web:
type: string
description: The end user's identifier on the web channel.
whatsapp:
type: object
description: The end user's WhatsApp identity.
properties:
phone:
type: string
description: Phone number in international format, for example +15551234567.
bsuid:
type: string
description: An alternate WhatsApp identifier for the end user.
ChannelConsent:
type: object
description: Current consent for one channel, and how it got there.
properties:
optedIn:
type: boolean
description: Whether the end user is currently opted in on this channel.
timestamp:
type: number
description: When the current state was set, in milliseconds since epoch.
source:
type: string
enum:
- csv_import
- api
- manual
- organic
- keyword
- bounce
description: What set the current state.
history:
type: array
description: Every earlier change, oldest first.
items:
$ref: '#/components/schemas/ConsentHistoryEntry'
required:
- optedIn
- timestamp
- source
- history
ConsentHistoryEntry:
type: object
description: One recorded change of consent state.
properties:
optedIn:
type: boolean
description: The consent state after this change.
timestamp:
type: number
description: When the change happened, in milliseconds since epoch.
source:
type: string
enum:
- csv_import
- api
- manual
- organic
- keyword
- bounce
description: What caused the change.
changedBy:
type: string
description: The member who made the change, when a person made it.
required:
- optedIn
- timestamp
- source
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key sent as Authorization: Bearer YOUR_API_KEY. Campaign endpoints
use campaign-scoped keys; the rest use organization or agent keys with
the matching permission.
````