Signing order

The rule in one sentence

Each participant set gets an order number starting at 1; sets with the same number act at the same time, and a number only starts when every set with a lower number has finished. Adobe enforces this on its side: people in a later step aren't emailed, can't see the document and get no signing link until their turn comes.

use Conceptlz\AdobeSign\Builder\{AgreementInfo, ParticipantSetInfo};

$agreement = AgreementInfo::create('Master Services Agreement')
    ->file($documentId)
    ->participantSet(ParticipantSetInfo::signer('client@customer.example')->order(1))
    ->participantSet(ParticipantSetInfo::signer('cfo@company.example')->order(2))
    ->participantSet(ParticipantSetInfo::approver('legal@company.example')->order(2))
    ->participantSet(ParticipantSetInfo::signer('ceo@company.example')->order(3));

Common patterns

Sequential

The default. Each set waits for the one before. When the order expresses authority (an employee signs, then a manager countersigns), sequential is usually what the business means.

// Three equivalent ways to write 1, 2, 3
$agreement->signers('employee@example.com', 'manager@company.example', 'hr@company.example');

$agreement->participantSet(ParticipantSetInfo::signer('employee@example.com'))
          ->participantSet(ParticipantSetInfo::signer('manager@company.example'))
          ->participantSet(ParticipantSetInfo::signer('hr@company.example'));

$agreement->participantSet(ParticipantSetInfo::signer('employee@example.com')->order(1))
          ->participantSet(ParticipantSetInfo::signer('manager@company.example')->order(2))
          ->participantSet(ParticipantSetInfo::signer('hr@company.example')->order(3));

Parallel

Everyone is emailed at once and can act in any order; the agreement completes when the last one has acted. Good for co-signers of equal standing (two founders, joint tenants) and the fastest way to collect signatures.

$agreement->participantSet(ParticipantSetInfo::signer('tenant1@example.com')->order(1))
          ->participantSet(ParticipantSetInfo::signer('tenant2@example.com')->order(1))
          ->participantSet(ParticipantSetInfo::signer('landlord@example.com')->order(1));

Mixed ("hybrid")

Some steps sequential, some parallel, as in the diagram above. This is the most natural fit for many real processes and the one that needs an account setting, covered in hybrid routing.

"Any one of these people"

Not an ordering feature, but often confused with parallel signing: a single set with several members is completed by whichever member acts first. Use it for "any director may sign for the company". Use parallel sets when you need everyone's signature.

// ONE signature from any director, then the customer
$agreement->participantSet(ParticipantSetInfo::signer('dir1@company.example', 'dir2@company.example')->order(1))
          ->participantSet(ParticipantSetInfo::signer('customer@example.com')->order(2));

How sets without order() are numbered

You can leave order() out. The builder then numbers each unnumbered set one more than the set added just before it (the first set gets 1). Explicit numbers are kept as they are. That gives intuitive results when you number everything or nothing, and surprising ones when you mix:

The consecutive-order rule

Adobe's spec requires the distinct order numbers to form "a valid consecutive increasing sequence": exactly 1, 2, …, n with no gaps, repeats allowed. Adobe rejects anything else, but with an error that doesn't say which number is wrong. The builder checks the rule locally, so a bad order never reaches the API:

Conceptlz\AdobeSign\Exception\InvalidArgumentException:
Signing orders must run 1..n without gaps (parallel sets share a number); got 1, 3.

The check runs when the agreement is built (toArray(), and so create()). It applies to builder agreements only; if you send a raw array or a generated model, Adobe does the checking.

Gaps usually appear when steps are optional: "legal reviews at step 2, but only for contracts over $100k". Build the list of steps first and number them afterwards, rather than hard-coding numbers:

$steps = [[ParticipantSetInfo::signer($deal->customerEmail)]];
if ($deal->value > 100_000) {
    $steps[] = [ParticipantSetInfo::approver('legal@company.example')];
}
$steps[] = [
    ParticipantSetInfo::signer('cfo@company.example'),        // these two share a step
    ParticipantSetInfo::signer('sales-director@company.example'),
];

foreach ($steps as $i => $sets) {
    foreach ($sets as $set) {
        $agreement->participantSet($set->order($i + 1));       // always 1..n
    }
}

Mixed orders need hybrid routing

Purely sequential orders (1, 2, 3) and purely parallel ones (1, 1, 1) always work. Mixing them (1, 2, 2, 3) is what Acrobat Sign calls hybrid routing, and it is an account setting that is off on many accounts, including new developer accounts. When it is off, Adobe refuses the agreement:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"code":"HYBRID_ROUTING_NOT_ALLOWED","message":"Hybrid routing is not enabled for this user"}

The SDK maps that code to AccountCapabilityException (a subclass of ApiException). The name says what to do: the request is valid, but the account doesn't allow it, so the fix is in Acrobat Sign's admin settings, not in your code. Nothing was created, and nobody was emailed.

use Conceptlz\AdobeSign\Exception\AccountCapabilityException;

try {
    $agreementId = $sign->agreements()->create($mixedOrderAgreement);
} catch (AccountCapabilityException $e) {
    if ($e->errorCode !== 'HYBRID_ROUTING_NOT_ALLOWED') {
        throw $e;
    }
    // Same people, strictly one after another: always allowed
    $logger->notice('Hybrid routing is off; sending sequentially. Ask an Acrobat Sign admin to enable it.');
    $agreementId = $sign->agreements()->create($sequentialAgreement);
}

Enabling it

1. Find an account administrator

   Only an Acrobat Sign account (or group) admin can change send settings. On a developer account, that is you.

2. Open the send settings

   In the Acrobat Sign web app, go to the account settings and open the Send Settings page. Look for the signing-order options and allow hybrid (mixed sequential and parallel) routing. Adobe's labels and menu layout change over time; Adobe's help pages on "hybrid signing order" describe the current location.

3. Check the group, too

   Settings can be overridden per group, and the error is about the sending user. If the account allows it but one user still gets the error, check the settings of that user's group.

4. Try again

   Re-run the request; no change in your code is needed. The package's live-lifecycle example ("a@x.com,b@x.com+c@x.com") is a quick way to confirm.

Whose turn is it?

Your UI will want to say "waiting for the CFO and legal", and your reminder job needs to know who to nudge. The answer comes from the participants endpoint.

agreements()->members(string $agreementId, bool $includeNextParticipantSet = false): arrayGET /agreements/{agreementId}/members

$members = $sign->agreements()->members($agreementId, includeNextParticipantSet: true);

// 1. Ask Adobe directly
$waitingFor = [];
foreach ($members['nextParticipantSets'] ?? [] as $set) {
    foreach ($set['memberInfos'] ?? [] as $member) {
        $waitingFor[] = $member['email'];
    }
}

// 2. Or read each step's status (works without the flag)
foreach ($members['participantSets'] ?? [] as $set) {
    $emails = implode(', ', array_column($set['memberInfos'] ?? [], 'email'));
    printf("%d  %-9s %-26s %s\n", $set['order'], $set['role'], $set['status'], $emails);
}

1  SIGNER    WAITING_FOR_OTHERS         client@customer.example
2  SIGNER    WAITING_FOR_MY_SIGNATURE   cfo@company.example
2  APPROVER  WAITING_FOR_MY_APPROVAL    legal@company.example
3  SIGNER    NOT_YET_VISIBLE            ceo@company.example

A step whose status starts with WAITING_FOR_MY_ is up now; NOT_YET_VISIBLE is a later step whose members haven't been told about the agreement yet. Match people by email or by member id, not by the order field of nextParticipantSets entries, which doesn't always mirror the step number.

The SDK uses the same information for reminders: agreements()->sendReminder($id) with no participant ids reminds whoever's turn it is, falling back to WAITING_FOR_MY_* statuses if Adobe leaves out nextParticipantSets. With webhooks, AGREEMENT_ACTION_COMPLETED tells you a step finished and AGREEMENT_ACTION_REQUESTED that the next one was asked to act; see Webhooks.

Signing URLs for embedded signing

By default, Adobe emails each person when their turn comes. For embedded signing, you show the signing page inside your own application instead: the customer finishes checkout and signs on the next screen, or a field agent hands a tablet to a client. Adobe gives you a signing URL for each person whose turn it currently is.

agreements()->signingUrls(string $agreementId, ?int $expiry = null, ?string $frameParent = null): SigningUrlResponseGET /agreements/{agreementId}/signingUrls

agreements()->signingUrlFor(string $agreementId, string $email, ?int $expiry = null): ?string

Signing links point at your account's data centre, for example https://secure.na4.adobesign.com/public/apiesign?pid=….

1. Create the agreement

   Optionally switch Adobe's initial emails off and set a post-sign redirect back to your app (see email options).

2. Wait until it is signable

   Retry signingUrlFor() on NotFoundException for a few seconds while Adobe processes the documents.

3. Authenticate your user, then fetch the link

   Request the link when the person opens the page, not in advance, and only after your own login has confirmed who they are.

4. Redirect or embed

   Redirect the browser to the link, or load it in an iframe on the $frameParent domain. After signing, Adobe sends them to your redirect URL.

use Conceptlz\AdobeSign\Exception\NotFoundException;

public function sign(string $contractId): Response
{
    $contract = $this->contracts->findForUser($contractId, $this->auth->user());   // your access check

    for ($attempt = 1; $attempt <= 5; $attempt++) {
        try {
            $url = $this->sign->agreements()->signingUrlFor(
                $contract->adobeAgreementId,
                $this->auth->user()->email,
                expiry: 600,                                     // 10 minutes is plenty to start
            );
            break;
        } catch (NotFoundException) {
            sleep(2);                                            // still processing; try again shortly
            $url = null;
        }
    }

    if ($url === null) {
        return $this->view('contracts/not-your-turn', ['contract' => $contract]);
    }

    return $this->redirect($url);
}

Where next

• Managing agreementsReminders, cancelling, updating and listing.
• WebhooksGet told when each step completes instead of polling.
• Identity verificationMake sure the person signing is the person you meant.
• Errors & exceptionsAccountCapabilityException and the other typed errors.

Common questions