Agents

An agent is the actual person assigned to a recipient role. While a recipient defines who needs to sign (the role), the agent defines who that person is (name, email, phone).

A recipient can have multiple agents assigned — for competitive multi-agent scenarios. See below.

---

Properties

Property	Type	Description
id	string	Unique identifier for this agent assignment.
name	string	Full name of the person.
email	string	Email address. Used to deliver signing invitations.
phone	string	Phone number. Used for SMS or WhatsApp OTP delivery.
locale	en-US | tr-TR	Language for the signing UI and notification emails.
phoneContactMethod	sms | whatsapp	OTP delivery channel when phone verification is required.
primary	boolean	Whether this agent is the primary agent for the recipient. See below.
context	object	Arbitrary metadata attached to this agent assignment.
contactId	string	Set if this agent was assigned via a contact reference.
groupId	string	Set if this agent was assigned via a contact group.
userId	string	Set if this agent was assigned via an internal team user.

---

Assigning agents

There are three ways to assign an agent to a recipient role:

1. Inline (direct person info)

Provide the person's details directly in the request. No prior setup required.

{
  "agents": [
    {
      "info": {
        "name": "Jane Smith",
        "email": "[email protected]",
        "phone": "+905001234567",
        "locale": "en-US",
        "phoneContactMethod": "whatsapp"
      }
    }
  ]
}

2. Contact reference

Reference an existing contact from your address book. The contact's name, email, phone, and locale are used automatically.

{
  "agents": [
    { "contactId": "cnt_07ab..." }
  ]
}

3. Internal user

Assign an internal Inspakt team member by their user ID.

{
  "agents": [
    { "userId": "usr_09cd..." }
  ]
}

---

Multi-agent recipients (competitive signing)

A single recipient role can have multiple agents assigned. This is useful when any one person from a group is sufficient to complete the signing — for example, when either of two co-signers can represent a company.

{
  "recipient": {
    "type": "signer",
    "identifier": "company_rep",
    "agents": [
      { "info": { "name": "Alice Johnson", "email": "[email protected]" } },
      { "info": { "name": "Bob Williams",  "email": "[email protected]"  } },
      { "info": { "name": "Carol Davis",   "email": "[email protected]" } }
    ]
  }
}

All three agents receive the signing invitation simultaneously. The first one to open and accept the signing session becomes the primary agent. The remaining agents are automatically released from the session once a primary has been established.

The primary: true flag on an agent indicates they are the active signer for that recipient slot.

---

Contact groups

Assigning a contact group to a recipient role automatically expands all group members into individual agents, enabling the same competitive signing behaviour without listing each person manually.

{
  "agents": [
    { "groupId": "grp_12ef..." }
  ]
}

See Contacts & Groups in the API Reference for managing groups.