Managing agreements

At a glance

Every method that calls the API throws an ApiException subclass on an error response and TransportException when no response arrives; the exceptions specific to a method are listed with it below. The full list is on Errors & exceptions.

Reading an agreement

agreements()->get(string $agreementId): AgreementGET /agreements/{agreementId}

$agreement = $sign->agreements()->get($agreementId);

$agreement->name;            // "Master Services Agreement"
$agreement->status;          // "OUT_FOR_SIGNATURE"
$agreement->isSigned();      // status === 'SIGNED'
$agreement->isOutForSignature();

$details = $agreement->details();   // Generated\Model\FetchedAgreementInfo, every field in the spec
$details->getParticipantSetsInfo();
$agreement->raw['locale'];          // or the decoded JSON, untouched

status($agreementId) is a shortcut for get($agreementId)->status. It makes the same request, so it also refreshes the remembered ETag.

Listing agreements

agreements()->all(int $pageSize = 100, ?string $externalId = null, ?string $groupId = null, ?bool $showHiddenAgreements = null): \GeneratorGET /agreements

// Every agreement visible to the caller, page by page
foreach ($sign->agreements()->all() as $summary) {
    printf("%s  %-28s %s\n", $summary->displayDate, $summary->status, $summary->name);
}

// Find the agreement(s) you created with ->externalId('crm-deal-42')
foreach ($sign->agreements()->all(externalId: 'crm-deal-42') as $summary) {
    $agreementId = $summary->id;
}

// Only the first 20, without fetching more pages than needed
foreach (new LimitIterator($sign->agreements()->all(pageSize: 20), 0, 20) as $summary) {
    // ...
}

AgreementSummary has $id, $name, $status, $type (AGREEMENT, MEGASIGN_CHILD, WIDGET_INSTANCE), $groupId, $displayDate, $hidden and $raw, plus details() for the generated AgreementAgreement model.

The status in a list row is relative to the caller: the same agreement can be WAITING_FOR_MY_SIGNATURE for one user and OUT_FOR_SIGNATURE for the sender. Use get() for the agreement's own status.

Breaking out of a foreach stops the paging, so searching a large account is cheap when the match is near the top. Avoid iterator_to_array() on a big account: it downloads every page. All list methods in the SDK work the same way (see the paging pattern).

Participants and whose turn it is

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

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

foreach ($members['participantSets'] as $set) {
    // $set['role'] SIGNER, $set['order'] 1, $set['status'] WAITING_FOR_MY_SIGNATURE / NOT_YET_VISIBLE / COMPLETED
    foreach ($set['memberInfos'] as $member) {
        echo "{$set['order']}. {$member['email']} ({$set['status']})\n";
    }
}

$waitingOn = array_merge(...array_map(
    fn (array $set) => array_column($set['memberInfos'], 'email'),
    $members['nextParticipantSets'] ?? [],
));

Each member has an id (the participant id used by sendReminder() and the participantId download options), an email and a securityOption.authenticationMethod showing the identity check that applies. The sender is under senderInfo.

The event history

agreements()->events(string $agreementId): AgreementEventListGET /agreements/{agreementId}/events

foreach ($sign->agreements()->events($agreementId)->getEvents() ?? [] as $event) {
    printf(
        "%s  %-24s %s\n",
        $event->getDate(),
        $event->getType(),            // CREATED, EMAIL_OTP_AUTHENTICATED, DOCUMENTS_VIEWED, ACTION_COMPLETED, DIGSIGNED, ...
        $event->getParticipantEmail(),
    );
}

Event types are strings, not an enum. Useful ones include ACTION_COMPLETED (someone signed or approved), DIGSIGNED (a certificate-based signature, see a real AES), EMAIL_OTP_AUTHENTICATED (see Identity verification) and DOCUMENTS_VIEWED. The live API sends some fields the generated model doesn't know (digitalSignatureInfo.providerName, for example); if you need those, decode the raw response yourself or use signatureEvidence(), which reads both spellings.

Reminders

agreements()->sendReminder(string $agreementId, ?array $participantIds = null, ?string $note = null): ReminderCreationResultPOST /agreements/{agreementId}/reminders

// Whoever's turn it is, with a personal note
$result = $sign->agreements()->sendReminder($agreementId, note: 'Friendly nudge: we need this by Friday.');

$result->id;                   // the reminder's id
$result->disabledRecipients;   // participants who won't get it (e.g. they turned reminder emails off)

// Specific people: participant ids from members()
$sign->agreements()->sendReminder($agreementId, ['CBJCHBCAABAAmem2']);

// Reminders on record, optionally by status: ACTIVE, CANCELED or COMPLETE
foreach ($sign->agreements()->reminders($agreementId, 'ACTIVE')->getReminderInfoList() ?? [] as $reminder) {
    echo $reminder->getReminderId(), ' next: ', $reminder->getNextSentDate(), "\n";
}

For automatic reminders, set them when you create the agreement: ->reminderFrequency(ReminderFrequency::DAILY_UNTIL_SIGNED) (also WEEKDAILY_UNTIL_SIGNED, EVERY_OTHER_DAY_UNTIL_SIGNED, EVERY_THIRD_DAY_UNTIL_SIGNED, EVERY_FIFTH_DAY_UNTIL_SIGNED, WEEKLY_UNTIL_SIGNED and ONCE). When it isn't set, the account's default applies.

Updating an agreement

agreements()->update(string $agreementId, AgreementInfo|FetchedAgreementInfo|array $info, ?bool $documentUpdateOnly = null): voidPUT /agreements/{agreementId}

1. Fetch

   get() returns the current details and remembers the ETag.

2. Modify

   Change only what you need on the generated FetchedAgreementInfo.

3. Put

   update() sends it back with If-Match, so it only succeeds if nobody changed the agreement in between.

$details = $sign->agreements()->get($agreementId)->details();

$details->setMessage('Updated: the price in clause 4 now includes VAT.');
$details->setExpirationTime('2026-12-31T23:59:59Z');

$sign->agreements()->update($agreementId, $details);

What Adobe lets you change depends on the agreement's state and on who has already acted; it answers with codes such as MODIFYING_IMMUTABLE_FIELDS (a ValidationException) or AGREEMENT_ALREADY_SIGNED when you try something it doesn't allow. Pass documentUpdateOnly: true when you only replace documents.

ETags in practice

Two people (or a person and a background job) can change the same agreement at nearly the same time. Without protection, the second write silently overwrites the first. Acrobat Sign prevents this with optimistic concurrency: every read returns an ETag, a version stamp, and a write that carries If-Match: <etag> is rejected with 412 Precondition Failed if the agreement has changed since. The SDK does the bookkeeping for you.

What the SDK does

• Every successful GET that returns an ETag is remembered for its path, and any ETag remembered for paths underneath it is forgotten, because the fresh read supersedes them.
• Every PUT or DELETE without an If-Match header gets the ETag remembered for the same path or, failing that, for the nearest parent. PUT /agreements/{id}/state therefore uses the ETag from GET /agreements/{id}, which is what Adobe expects.
• After a successful write, everything remembered for that resource is forgotten. Only a write to the resource itself (PUT /agreements/{id}) stores the new ETag from its response. A write to a sub-resource such as /state stores nothing, because Adobe changes the parent's ETag too. Reusing it caused 412s in live testing.
• A 412 becomes PreconditionFailedException (Adobe's code is usually RESOURCE_MODIFIED).

What that means for your code

The ETag memory belongs to the AdobeSign instance (and the copies made with asUser(), which share it) and keeps the most recent 500 paths. In a PHP-FPM request that means "this request"; in a long-running queue worker it lasts longer, which is harmless because an outdated ETag only leads to a 412 and a re-fetch. The ETag of the last read is also on Agreement::$etag if you want to log it. To turn the behaviour off, use new ClientOptions(autoEtag: false); writes are then always unconditional. See Data centres, retries & ETags for the rest of the HTTP pipeline.

Handling a 412

A conflict is not an error in your data; it means "look again". Re-fetch, re-apply your change and retry a couple of times:

use Conceptlz\AdobeSign\AdobeSign;
use Conceptlz\AdobeSign\Exception\PreconditionFailedException;
use Conceptlz\AdobeSign\Generated\Model\FetchedAgreementInfo;

/** @param callable(FetchedAgreementInfo): void $change */
function updateAgreement(AdobeSign $sign, string $agreementId, callable $change, int $attempts = 3): void
{
    for ($attempt = 1; ; $attempt++) {
        $details = $sign->agreements()->get($agreementId)->details();   // fresh data and ETag
        $change($details);

        try {
            $sign->agreements()->update($agreementId, $details);
            return;
        } catch (PreconditionFailedException $e) {
            if ($attempt >= $attempts) {
                throw $e;
            }
            usleep(500_000 * $attempt);   // Adobe may still be busy with the agreement
        }
    }
}

updateAgreement($sign, $agreementId, fn (FetchedAgreementInfo $d) => $d->setMessage('Please sign by Friday.'));

Changing state

agreements()->updateState(string $agreementId, string $state, array $extra = []): voidPUT /agreements/{agreementId}/state

// Send an agreement created as a draft or in AUTHORING
$sign->agreements()->updateState($agreementId, 'IN_PROCESS');

// Restart with a message to the participants
$sign->agreements()->updateState($agreementId, 'RESTART', [
    'agreementRestartInfo' => ['message' => 'We corrected the delivery address. Please sign again.'],
]);

Which transitions are allowed depends on the current state and the account; Adobe refuses the others with an ApiException whose $errorCode says why (for example OPERATION_NOT_ALLOWED or UNABLE_TO_RESTART_AGREEMENT). Call get() first if you want the write guarded by If-Match.

Cancelling an agreement

agreements()->cancel(string $agreementId, ?string $comment = null, bool $notifyOthers = true): voidPUT /agreements/{agreementId}/state

$sign->agreements()->get($agreementId);   // optional: guard the cancel with If-Match
$sign->agreements()->cancel($agreementId, 'Sent to the wrong address, a corrected version follows.');

// Quietly, e.g. cleaning up test agreements
$sign->agreements()->cancel($agreementId, notifyOthers: false);

A cancelled agreement stays in the account with status CANCELLED and its history. You cannot cancel an agreement that is already signed; Adobe answers with an error.

Embedded signing links

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

agreements()->signingUrlFor(string $agreementId, string $email, ?int $expiry = null): ?stringGET /agreements/{agreementId}/signingUrls

use Conceptlz\AdobeSign\Exception\NotFoundException;

try {
    $url = $sign->agreements()->signingUrlFor($agreementId, $user->email, expiry: 900);
} catch (NotFoundException $e) {
    // $e->errorCode === 'AGREEMENT_NOT_SIGNABLE': still processing; try again shortly
    $url = null;
}

if ($url === null) {
    return view('contract.waiting');      // not their turn (yet)
}
return redirect($url);

// All current links, grouped by participant set
foreach ($sign->agreements()->signingUrls($agreementId)->getSigningUrlSetInfos() ?? [] as $set) {
    foreach ($set->getSigningUrls() ?? [] as $link) {
        echo $link->getEmail(), ': ', $link->getEsignUrl(), "\n";
    }
}

Treat signing links like passwords: anyone holding one can open the signing page (identity checks still apply). Generate them on demand for the logged-in user and keep the expiry short.

Adobe's pages: views

agreements()->views(string $agreementId, string $name = 'ALL', array $configuration = []): AgreementViewsPOST /agreements/{agreementId}/views

// Let a sender place fields on an agreement created with ->state(AgreementState::AUTHORING)
$views = $sign->agreements()->views($agreementId, 'AUTHORING', [
    'commonViewConfiguration' => ['noChrome' => true, 'autoLoginUser' => false, 'locale' => 'en_GB'],
]);

foreach ($views->getAgreementViewList() ?? [] as $view) {
    echo $view->getName(), ' ', $view->getUrl(), ' (expires ', $view->getExpiration(), ")\n";
}

Copying an agreement

agreements()->copy(string $agreementId): stringPOST /agreements/{agreementId}/copy

$newId = $sign->agreements()->copy($agreementId);
$sign->agreements()->updateState($newId, 'IN_PROCESS');

Form fields and entered data

agreements()->formFields(string $agreementId): AgreementFormFieldsResponseGET /agreements/{agreementId}/formFields

foreach ($sign->agreements()->formFields($agreementId)->getFields() ?? [] as $field) {
    echo $field->getName(), ' (', $field->getInputType(), ')', $field->getRequired() ? ' required' : '', "\n";
}

The values signers typed come from formData($agreementId), a CSV stream that only the agreement's creator can read. It is covered with the other downloads in Downloading signed files.

Acting for another user

Agreements belong to the user who sent them. With an admin-level token, asUser() gives you a client that acts as someone else in the account, which you need to manage agreements your integration didn't send itself:

$asSales = $sign->asUser('email:sales-lead@example.com');
$asSales->agreements()->cancel($agreementId, 'Superseded by the renewal.');

See Authentication for the details.

Common questions

Where next

• Downloading signed filesThe signed PDF, the audit report and the form data.
• WebhooksStop polling: get told when something happens.
• Signature levelsCheck which level each signer reached.
• Data centres, retries & ETagsThe HTTP pipeline underneath every call.