How Acrobat Sign works

The big picture

You upload one or more documents. You create an agreement that bundles those documents with a list of participant sets, each with a role (sign, approve, fill in a form…) and a place in the signing order. Adobe emails whoever is first, records every step in an audit trail, moves the agreement through a series of statuses, and when the last person has acted, seals the final PDF. You follow along by polling or through webhooks, then download the signed file.

• DocumentA file to be signed. Uploaded temporarily (transient), kept as a reusable template (library) or fetched from a URL.
• AgreementOne signing transaction: documents + participants + options. Has an id, a status and a history.
• Participant setOne step of the workflow: a role, an order number and one or more members.
• MemberA person (email address) in a participant set. Any one member can act for the whole set.
• StatusWhere the agreement is now, as Adobe reports it: OUT_FOR_SIGNATURE, SIGNED, CANCELLED…
• EventOne entry in the audit trail: created, emailed, viewed, signed, with who, when and from where.
• Data centreThe regional cluster (shard) your account lives on, such as na4 or eu1. Every API call must go there.

Documents: transient, library and URL

Acrobat Sign never signs a file "in place" on your server. It needs its own copy, and there are three ways to give it one. All three end up as an entry in the agreement's list of files (fileInfos in the API, FileInfo in the SDK).

"Transient" catches people out. The upload is a staging area, not storage: the id stops working after seven days, and you can't list or download transient documents. Once an agreement has been created from it, the agreement holds its own copy, so the seven-day limit no longer matters. Details and edge cases are in Uploading documents.

Agreements

An agreement is the unit of work in Acrobat Sign: "these documents, for these people, in this order". It has a name (shown in emails and the web app), an id that looks like CBJCHBCAABAA…, a sender, a status and an event history. Once sent, its documents are fixed: you can change some details (the message, the expiry, participants in some cases) but not the file being signed. To send a corrected document, cancel and send a new agreement, or use agreements()->copy() to start a new draft with the same set-up.

Adobe merges the documents in the order you added them. At the end you can download each one separately or all of them as one combined PDF, with or without the audit report.

Participant sets and members

The most important idea in the Acrobat Sign data model is that you don't add people to an agreement; you add participant sets. A set is one step of the workflow. It has:

• a role: what this step does (sign, approve, accept, fill in fields…);
• an order: when this step happens (1, 2, 3…; sets with the same number happen in parallel);
• one or more members: the people who can perform it.

The rule that matters: any one member can complete the set for everyone. A set with two members is "either of these people signs", not "both of these people sign". If you need both signatures, use two sets.

use Conceptlz\AdobeSign\Builder\ParticipantSetInfo;

// Either partner may sign for the firm: ONE signature is collected
ParticipantSetInfo::signer('alice@firm.example', 'bob@firm.example');

// Both must sign, at the same time: TWO signatures are collected
ParticipantSetInfo::signer('alice@firm.example')->order(1);
ParticipantSetInfo::signer('bob@firm.example')->order(1);

The "group" form is useful for shared mailboxes and teams ("anyone in accounts payable can approve"). Every member receives the email; the first to act completes the step and the others are released.

Roles

The role decides what Adobe asks the person to do and which emails they get. The SDK has a ParticipantRole enum with every role the v6 API accepts, plus shortcuts for the two common ones (ParticipantSetInfo::signer() and ::approver()). Any other role goes through ParticipantSetInfo::role().

Responses can contain two more roles you never send: SENDER and SHARE. They describe the agreement's owner and people it was shared with. Treat roles (and statuses) as open-ended strings: Adobe adds values without changing the API version, which is why the SDK's models keep them as plain strings.

CCs and the sender

A CC receives copies of the emails and the final PDF but takes no action; add CCs with AgreementInfo::cc(). The sender is the Acrobat Sign user who created the agreement. They own it, can cancel or remind, and receive status emails. The sender doesn't sign unless you also add them as a participant.

State versus status

The API uses two similar words for two different things, and mixing them up is the most common source of confusion.

• StateWhat you ask for: the stage you want the agreement to be in. You set it when creating (AgreementInfo::state()) and change it with agreements()->updateState(). Adobe never returns it in GET /agreements/{id}.
• StatusWhat Adobe reports: where the agreement actually is. Read it with agreements()->status($id) or get($id)->status.

The three creation states

Adobe's allowed path is DRAFT → AUTHORING → IN_PROCESS → CANCELLED, changed with agreements()->updateState($id, 'IN_PROCESS') and friends. Draft and authoring agreements don't expire: the expiry countdown starts when the agreement is sent.

Statuses you will see

The SDK's Agreement model adds two shortcuts for the statuses most code cares about: isSigned() and isOutForSignature(). For anything else compare $agreement->status as a string, and give unknown values a sensible default.

Each step has a status too

agreements()->members($id) returns every participant set with its own status. That is how you tell whose turn it is:

Pass includeNextParticipantSet: true to also get nextParticipantSets, the steps whose turn it is. Adobe leaves that key out unless you ask, even though the spec lists it. The signing order guide shows both techniques.

The first few seconds

Creating an agreement returns its id immediately, but Adobe processes the documents in the background. For a few seconds the status is DOCUMENTS_NOT_YET_PROCESSED, some calls answer AGREEMENT_NOT_EXPOSED or AGREEMENT_NOT_SIGNABLE (both surface as NotFoundException), and participant data can lag behind the status. Code that creates and then immediately inspects an agreement should poll briefly:

$status = $sign->agreements()->status($agreementId);
for ($i = 0; $status === 'DOCUMENTS_NOT_YET_PROCESSED' && $i < 15; $i++) {
    sleep(2);
    $status = $sign->agreements()->status($agreementId);
}

If a conversion fails (a corrupt or password-protected file, for example), Adobe cancels the agreement itself and records an AUTO_CANCELLED_CONVERSION_PROBLEM event.

Events and the audit trail

Acrobat Sign records everything that happens to an agreement as an event: created, emailed (ACTION_REQUESTED), email opened (EMAIL_VIEWED), documents viewed, identity checked (EMAIL_OTP_AUTHENTICATED…), signed (ACTION_COMPLETED; DIGSIGNED for a certificate-based signature), delegated, declined (REJECTED), cancelled (RECALLED), expired. Each event carries a date, the participant's email, the acting user and, for signatures, details such as the input type (typed, drawn, image) and the IP address.

The same history is available in three forms:

foreach ($sign->agreements()->events($agreementId)->getEvents() ?? [] as $event) {
    printf("%s  %-22s %s\n", $event->getDate(), $event->getType(), $event->getParticipantEmail());
}

2026-11-03T14:02:11Z  CREATED                sender@example.com
2026-11-03T14:02:13Z  ACTION_REQUESTED       jane@example.com
2026-11-03T14:05:40Z  EMAIL_VIEWED           jane@example.com
2026-11-03T14:06:02Z  ACTION_COMPLETED       jane@example.com

Data centres (shards) and base URIs

Acrobat Sign runs in several regional data centres. Adobe calls them shards, and their names appear in host names: na1, na4, eu1, eu2, jp1, au1 and so on. An account lives in exactly one, chosen when it was created (an EU customer is usually on an EU shard, which matters for data residency).

Every account has two addresses on its shard:

Calls sent to the wrong shard fail with 403 INVALID_API_ACCESS_POINT. Adobe provides a shard-neutral host, api.adobesign.com, whose GET /baseUris tells you where an account lives. The SDK handles all of this:

1. Discover once

   On the first call it asks GET /baseUris with your credentials.

2. Cache

   It stores the answer in the PSR-16 cache you passed (in memory by default) for 24 hours, keyed by a hash of the credential, never the credential itself.

3. Recover

   If Adobe ever answers INVALID_API_ACCESS_POINT (the account was moved), it forgets the cached shard, rediscovers it and retries the request once.

OAuth is simpler still: Adobe returns the shard (api_access_point) with the token, so OAuth clients never need GET /baseUris. US government accounts live on a separate domain (adobesigngov.us); for those, change ClientOptions::$bootstrapUrl as described in Configuration.

Users: sender, acting user and participant

Three different "who" questions come up, and the API answers each in a different place.

An account administrator's credentials can act as another user in the same account, so that agreements are sent from the right person's name and appear in their list. The SDK exposes this as asUser(), which adds Adobe's x-api-user header:

// Same account, different user: the agreement shows maria@company.example as the sender
$asMaria = $sign->asUser('maria@company.example');
$agreementId = $asMaria->agreements()->create($agreement);

// $sign itself is unchanged and still acts as the key's owner
$sign->agreements()->all();

Users also belong to groups, which carry their own settings (email templates, signing options, which identity checks are allowed). An agreement belongs to the sender's primary group unless you set another. Many "why does this work for one user but not another?" questions come down to group settings. Authentication covers asUser() in depth.

Where next

• Uploading documentsPaths, streams, mime types and the seven-day rule.
• Creating agreementsThe AgreementInfo builder, option by option.
• Signing orderSequential, parallel and mixed steps, and whose turn it is.
• Managing agreementsReminders, cancelling, updating and listing.

Common questions