Leads

Add context to a lead

Adds context or a timeline event to a lead. Use event for things that happened at a point in time (a status change, a completed step, an update from your system) — Apten places it in the conversation timeline so the AI knows when it occurred relative to the lead’s messages and can react to it. Use context for standing facts and instructions that should always apply regardless of when they were added (preferences, rules, background). At least one of context, event, additionalInfo, or command is required; they can be combined in one call.

POST

leads

{leadId}

addContext

cURL

curl --request POST \
  --url https://api.attent.app/v1/leads/{leadId}/addContext \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "context": "The lead prefers to be contacted in the evenings.",
  "event": "The lead scheduled a meeting with our team for Monday at 2pm.",
  "additionalInfo": {
    "favoriteColor": "blue",
    "favoriteFood": "pizza"
  },
  "command": "Schedule a follow up for next week."
}
'

import requests

url = "https://api.attent.app/v1/leads/{leadId}/addContext"

payload = {
    "context": "The lead prefers to be contacted in the evenings.",
    "event": "The lead scheduled a meeting with our team for Monday at 2pm.",
    "additionalInfo": {
        "favoriteColor": "blue",
        "favoriteFood": "pizza"
    },
    "command": "Schedule a follow up for next week."
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    context: 'The lead prefers to be contacted in the evenings.',
    event: 'The lead scheduled a meeting with our team for Monday at 2pm.',
    additionalInfo: {favoriteColor: 'blue', favoriteFood: 'pizza'},
    command: 'Schedule a follow up for next week.'
  })
};

fetch('https://api.attent.app/v1/leads/{leadId}/addContext', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.attent.app/v1/leads/{leadId}/addContext",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'context' => 'The lead prefers to be contacted in the evenings.',
    'event' => 'The lead scheduled a meeting with our team for Monday at 2pm.',
    'additionalInfo' => [
        'favoriteColor' => 'blue',
        'favoriteFood' => 'pizza'
    ],
    'command' => 'Schedule a follow up for next week.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.attent.app/v1/leads/{leadId}/addContext"

	payload := strings.NewReader("{\n  \"context\": \"The lead prefers to be contacted in the evenings.\",\n  \"event\": \"The lead scheduled a meeting with our team for Monday at 2pm.\",\n  \"additionalInfo\": {\n    \"favoriteColor\": \"blue\",\n    \"favoriteFood\": \"pizza\"\n  },\n  \"command\": \"Schedule a follow up for next week.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.attent.app/v1/leads/{leadId}/addContext")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"context\": \"The lead prefers to be contacted in the evenings.\",\n  \"event\": \"The lead scheduled a meeting with our team for Monday at 2pm.\",\n  \"additionalInfo\": {\n    \"favoriteColor\": \"blue\",\n    \"favoriteFood\": \"pizza\"\n  },\n  \"command\": \"Schedule a follow up for next week.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.attent.app/v1/leads/{leadId}/addContext")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"context\": \"The lead prefers to be contacted in the evenings.\",\n  \"event\": \"The lead scheduled a meeting with our team for Monday at 2pm.\",\n  \"additionalInfo\": {\n    \"favoriteColor\": \"blue\",\n    \"favoriteFood\": \"pizza\"\n  },\n  \"command\": \"Schedule a follow up for next week.\"\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Success"
}

{
  "message": "<string>"
}

{
  "message": "Forbidden"
}

{
  "message": "Internal Server Error"
}

Authorizations

x-api-key

string

header

required

Path Parameters

leadId

string

required

The ID of the lead to add context to.

Body

application/json

The lead's context and/or timeline event, and an optional command.

context

string

A standing fact or instruction about the lead that should always apply, regardless of when it was added. For something that happened at a point in time, use event instead.

event

string

Something that just happened, stated as a short factual sentence (what changed, and the next step if there is one). Apten records it in the conversation timeline with a timestamp: the AI knows when it occurred relative to the lead's messages, treats it as information the lead has not seen, and can bring it up naturally or act on it in the flow-chart conversation. Example: 'Application submitted. Next step: upload proof of residence.'

additionalInfo

object

An key-value object containing structured data to store with the lead. These will be stored as variables that can be accessed in the flow-chart conversation prompts.

command

string

An optional command for Apten regarding the lead. Currently allowed commands are scheduling a follow up and sending a message.

Response

Context has successfully been added to the lead.

message

string

Returns "Success" if the context was added successfully.

cURL

curl --request POST \
  --url https://api.attent.app/v1/leads/{leadId}/addContext \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "context": "The lead prefers to be contacted in the evenings.",
  "event": "The lead scheduled a meeting with our team for Monday at 2pm.",
  "additionalInfo": {
    "favoriteColor": "blue",
    "favoriteFood": "pizza"
  },
  "command": "Schedule a follow up for next week."
}
'

import requests

url = "https://api.attent.app/v1/leads/{leadId}/addContext"

payload = {
    "context": "The lead prefers to be contacted in the evenings.",
    "event": "The lead scheduled a meeting with our team for Monday at 2pm.",
    "additionalInfo": {
        "favoriteColor": "blue",
        "favoriteFood": "pizza"
    },
    "command": "Schedule a follow up for next week."
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    context: 'The lead prefers to be contacted in the evenings.',
    event: 'The lead scheduled a meeting with our team for Monday at 2pm.',
    additionalInfo: {favoriteColor: 'blue', favoriteFood: 'pizza'},
    command: 'Schedule a follow up for next week.'
  })
};

fetch('https://api.attent.app/v1/leads/{leadId}/addContext', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.attent.app/v1/leads/{leadId}/addContext",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'context' => 'The lead prefers to be contacted in the evenings.',
    'event' => 'The lead scheduled a meeting with our team for Monday at 2pm.',
    'additionalInfo' => [
        'favoriteColor' => 'blue',
        'favoriteFood' => 'pizza'
    ],
    'command' => 'Schedule a follow up for next week.'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.attent.app/v1/leads/{leadId}/addContext"

	payload := strings.NewReader("{\n  \"context\": \"The lead prefers to be contacted in the evenings.\",\n  \"event\": \"The lead scheduled a meeting with our team for Monday at 2pm.\",\n  \"additionalInfo\": {\n    \"favoriteColor\": \"blue\",\n    \"favoriteFood\": \"pizza\"\n  },\n  \"command\": \"Schedule a follow up for next week.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.attent.app/v1/leads/{leadId}/addContext")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"context\": \"The lead prefers to be contacted in the evenings.\",\n  \"event\": \"The lead scheduled a meeting with our team for Monday at 2pm.\",\n  \"additionalInfo\": {\n    \"favoriteColor\": \"blue\",\n    \"favoriteFood\": \"pizza\"\n  },\n  \"command\": \"Schedule a follow up for next week.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.attent.app/v1/leads/{leadId}/addContext")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"context\": \"The lead prefers to be contacted in the evenings.\",\n  \"event\": \"The lead scheduled a meeting with our team for Monday at 2pm.\",\n  \"additionalInfo\": {\n    \"favoriteColor\": \"blue\",\n    \"favoriteFood\": \"pizza\"\n  },\n  \"command\": \"Schedule a follow up for next week.\"\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Success"
}

{
  "message": "<string>"
}

{
  "message": "Forbidden"
}

{
  "message": "Internal Server Error"
}

API Reference

Leads

Calls

Tags

Usage

Do Not Contact

Add context to a lead

Authorizations

Path Parameters

Body

Response