People on a lead (contacts)

A lead (a table_entries row) is a request. The people on it — the parent who enquired, the children who would train — are contacts: records that exist once per organisation and are shared by every request they appear on.

You state who is on a lead with a contacts array. The same document is accepted by POST/PATCH /connect/table_entries and by ingress webhooks, with the same rules. This page is the reference for both.

The document

{
    "contacts": [
        {
            "firstName": "Mika",
            "lastName": "Toivonen",
            "isPrimary": true,
            "isSubject": false,
            "channels": [
                {"kind": "phone", "value": "+4917612345678"},
                {"kind": "email", "value": "mika@example.com"}
            ]
        },
        {"firstName": "Aino", "lastName": "Toivonen", "isSubject": true}
    ]
}

Field	Notes
firstName, middleName, lastName	The name in parts.
fullName	The name whole, when you don’t know the parts. Send either fullName or the parts — never both. A person with no name at all is allowed.
channels	Up to 20 per person. Each is {kind: "email" | "phone", value, isPrimary?}.
isPrimary	Who you contact about this lead. See Rules.
isSubject	Whether the lead is about this person — who would attend. Defaults to true.
contactId	Attach an existing person instead of describing one. See Attaching.

The people are written in the same transaction as the lead: they land together, or the request is a 400 and neither exists.

Roles

Two independent flags, because they answer different questions:

• isPrimary — the one person this lead displays and addresses. Messages go to them.
• isSubject — who the lead is about. Any number of people.

One person can be both, and for a single adult enquiring for themselves usually is. A parent enquiring for a child is the other shape: the parent is primary and not a subject, the child is a subject.

isSubject defaults to true

Omitting isSubject makes the person a subject. For a parent enquiring on behalf of a child, send "isSubject": false on the parent explicitly — otherwise the parent counts as a participant too, and automations that name the participants will name them.

Every lead with people on it has at least one subject. If a document marks nobody as a subject, the primary contact is made the subject rather than the lead being refused.

isSubject was called isParticipant until September 2026. The old name is still accepted on writes and takes effect when isSubject is absent, but it is deprecated, never returned, and will be removed. Send isSubject.

Rules

• One primary, once there is a choice. A single person is the primary by being the only one, so isPrimary is optional there. With two or more people, exactly one must carry isPrimary: true — zero or two is refused.
• One primary channel per kind, once there is a choice. A single email or phone number is made primary for you. Two of the same kind need exactly one marked isPrimary: true.
• Every person appears once. A repeated contactId is refused.
• A name is whole or in parts, never both.
• An empty array is valid. A lead need not have anyone on it.

Matching: sending a person twice does not create them twice

Omitting contactId does not always create a new person. RocketLead first looks for someone the organisation already holds:

• A person is attached automatically when an existing contact has the same name and already holds every channel you sent. Sending the same family twice therefore puts both requests on the same people.
• A match is never used to add anything to an existing person. If you send a channel the existing contact does not have, a new contact is created. Likely pairs are later offered to the studio as possible duplicates to review and merge in the console.
• A person sent without channels (typically a child) is matched only among the children already on the same primary contact’s other requests.

Each request is still its own lead. Matching links people, never merges or closes requests.

Attaching an existing person

Give contactId to put a known person on the lead. Attaching only attaches: the name and channels beside a contactId are ignored, and the person is not edited. An unknown, deleted or other-organisation contactId is refused.

Updating: the array is the complete set

On PATCH, a contacts array replaces who is on the lead — anyone absent is taken off it. It is not merge-patched like data. An update that is not about people omits contacts entirely.

Taking a person off a lead never deletes the person; they stay on their other requests.

The Connect API cannot edit a person’s name or channels. That is done in the console, where the change applies to every request the person is on.

Identity in data is ignored

Name, email and phone keys in data or customFieldData are still accepted and stored, and read by nothing: they do not name the lead, reach automations, or show in the console. A lead sent with identity only in data and no contacts array has nobody on it.

They are also a second copy of somebody’s details that the console never updates. Move identity into contacts; dropping the old keys at the same time changes nothing.

Reading people back

Surface	Returns the people?
Ingress webhook response	Yes — an identity object with each person’s id. See Ingress → Response.
POST / PATCH /connect/table_entries	No — the response is the lead without its people.

The Connect API has no endpoint that reads a lead or its people. If your integration needs the IDs of the people it created, use an ingress webhook for the create.

Booking a specific person

POST /connect/calendar_bookings/ accepts participantContactId: the person on the lead the appointment is for. It must be someone on the lead given as entryId.

Omit it and RocketLead decides: a lead with exactly one subject books that person; a lead with several books the request without naming anyone. See Bookings.

Related

• Leads — the endpoints that take this document.
• Ingress webhooks — the token-only alternative, which returns the people it created.
• Automation variables — $contact, $subjects, $attendees.