Thalamus API: Introduction & Basics

Thalamus provides a REST/JSON API that allows developers to integrate their applications and websites (referred to as "touchpoints") with the Thalamus platform. The API publishes a series of services that touchpoints can call to receive specific responses.

📝 A Note on Server Configuration: Each Thalamus server has its own unique configuration. This documentation is a general guide, but specific changes may apply to your server instance. Before beginning development, you should always check with the instance owner about the following:

• Available profile fields and which ones are required.

• The configured Opt-In strategy.

• Specific server URLs, touchpoint codes, and API tokens.

---

API Basics

The API follows standard REST conventions but also incorporates some concepts from classic web applications, like the notion of a "current user" in a session.

REST Conventions

For interacting with entities, the API uses standard URLs and HTTP verbs:

• Get a list of entities: GET /api/<entity_name>

• Get a single entity: GET /api/<entity_name>/<id>

• Create an entity: POST /api/<entity_name>

• Update an entity: PUT /api/<entity_name>/<id>

• Delete an entity: DELETE /api/<entity_name>/<id> (Rarely available)

"Current User" Context

Like a website, the Thalamus API maintains the context of a "current user" after login. This simplifies some requests by removing the need to specify the user's ID in the URL. For example:

• Update current user's profile: PUT /api/people/profile

• Get current user's consumer info: GET /api/people/consumer

Common Response Structure

Most responses from the API share a common JSON structure:

{
  "links": [],
  "data": {
    "activities": [],
    "entity": {}
  },
  "errors": {}
}

• links: An array of navigational links available from the "current page" or context.

• data: An object containing the primary response data, which includes a list of relevant activities and the entity that was requested, created, or updated.

• errors: An object containing key-value pairs detailing any errors that occurred.

---

Handling Data

Sending Values

When creating or updating an entity, field values are handled in three ways:

1. Set a value: Send the field with its new value (e.g., "name": "John").

2. Delete a value: Send the field with a null value (e.g., "name": null).

3. Do not change a value: Omit the field entirely from your request. Thalamus will keep the existing value as is.

Handling Cookies

Thalamus uses cookies to identify requests from the same consumer and touchpoint. The best practice is to always keep all cookies received in a Thalamus response and send them back in the next request.

⚠️ Critical Cookies: Two cookies are critical for the services to function correctly: jsessionId and AWSELB. Ensure these are always sent back in subsequent requests.

---

Common Parameters

Nearly every request to the Thalamus API should include a set of common parameters. These can be sent either as HTTP Headers or as Query Parameters in the URL.

Parameter	Required?	Description
Touchpoint	Required	The code identifying your application or website.
Token	Required	The static API token for your touchpoint.
Activity	Optional	The name of the activity context for the request.
source	Optional	Identifies the session, often added automatically by Thalamus.
Tags	Optional	A comma-separated list of tags for tracking interactions.
Error Version	Optional	A version number to request a different error message format.

The specific values for these parameters are configured in the Thalamus Back Office and must be provided by your Thalamus Administrator.

Touchpoint

• Header Key: Thalamus-Touchpoint

• Query Key: touchpoint

Token

• Header Key: Thalamus-Token

• Query Key: token

Activity

• Header Key: Thalamus-Activity

• Query Key: activity

Source

• Header Key: Thalamus-Source

• Query Key: source

• Note: Thalamus automatically adds the source query parameter to <a> links in communications. This allows Thalamus to identify the party's session during login or registration.

Tags

• Header Key: Thalamus-Tags

• Query Key: tags

• Format: A comma-separated string of up to 25 tags (e.g., halloween,parade,dinner).

Error Version

• Query Key: ev

• Format: A version number (e.g., ev=2) to request an alternative error format. This parameter can only be sent as a query parameter.

---

HTTP Response Codes

Thalamus uses standard HTTP response codes to indicate the success or failure of a request.

Code	Status Name	Description
200	OK	The request was successful.
201	CREATED	The resource sent by the client has been successfully created within Thalamus' database.
400	Bad Request	The request was malformed, often due to invalid JSON or data that fails validation.
401	Unauthorized	You must authenticate before accessing the resource (e.g., the user is not logged in).
404	Not Found	The requested resource or URL could not be found.
500	Internal Server Error	An unexpected error occurred on the server side.

---

Typical Flow & Best Practices

A typical integration involves a flow where a user visits a website, logs in or registers, interacts with features, and eventually logs out.

Health Check: isAlive

Before displaying links for Login, Registration, or Password Recovery, it is a best practice to first call the isAlive service.

If the isAlive service does not return a 200 OK response, it means the server is down or unreachable. In this case, you should not render these links to prevent users from navigating to pages that will not work.