Using the client

Three ways in

There is one configured client per scope (request or job), and three ways to get at it. They all end up at the same object, so pick whichever reads best in the place you're writing code.

The facade

The facade class is Conceptlz\AdobeSign\Laravel\Facades\AdobeSign, auto-registered under the global alias AdobeSign. Its short name is the same as the core client class Conceptlz\AdobeSign\AdobeSign, so when a file needs both, alias one of them:

use Conceptlz\AdobeSign\Laravel\Facades\AdobeSign as Sign;

final class AgreementStatusController
{
    public function __invoke(Contract $contract): JsonResponse
    {
        return response()->json([
            'status' => Sign::agreements()->status($contract->adobe_agreement_id),
        ]);
    }
}

The facade's docblock lists every method with its types, so your IDE and static analysis know that Sign::agreements() returns Conceptlz\AdobeSign\Resource\Agreements. The full list is in the reference.

Injecting the client

The service provider binds the core class Conceptlz\AdobeSign\AdobeSign to AdobeSignManager::client(). Type-hint it anywhere Laravel resolves dependencies: controller actions and constructors, job handle() methods, listeners, commands.

use Conceptlz\AdobeSign\AdobeSign;

public function show(string $agreementId, AdobeSign $sign): JsonResponse
{
    $agreement = $sign->agreements()->get($agreementId);

    return response()->json([
        'id' => $agreement->id,
        'name' => $agreement->name,
        'status' => $agreement->status,   // e.g. OUT_FOR_SIGNATURE, SIGNED, CANCELLED
    ]);
}

Injection makes dependencies visible and keeps classes easy to test. Which client you get depends on ADOBE_SIGN_AUTH: the Integration Key client, or with oauth the signed-in user's connection.

Injecting the manager

When one piece of code works with several connections, inject the manager and ask it for the client you need:

use Conceptlz\AdobeSign\Laravel\AdobeSignManager;

public function handle(AdobeSignManager $adobe): void
{
    foreach (User::whereNotNull('adobe_sign_connected_at')->cursor() as $user) {
        if (! $adobe->isConnected($user)) {
            continue;
        }

        foreach ($adobe->forUser($user)->agreements()->all(pageSize: 50) as $summary) {
            // $summary->id, $summary->name, $summary->status
        }
    }
}

What the container holds

"Scoped" is what makes the package safe under Octane and in queue workers: a manager never outlives the request or job that created it, so one user's OAuth client can't leak into the next request. Laravel also clears resolved facade instances between queued jobs, so the facade follows the same rule.

The manager's methods

Every method below is available on the manager, through injection, and through the facade.

client(): Conceptlz\AdobeSign\AdobeSign

forUser(Authenticatable|string|int $user): Conceptlz\AdobeSign\AdobeSign

$id = AdobeSign::forUser($request->user())->agreements()->create($info);

isConnected(Authenticatable|string|int $user): bool

oauth(): Conceptlz\AdobeSign\Auth\OAuthClient

tokens(): Conceptlz\AdobeSign\Auth\TokenStore

webhookHandler(): Conceptlz\AdobeSign\Webhook\WebhookHandler

userKey(Authenticatable|string|int $user): string
static resolveUserKeyUsing(?callable $resolver): void

use Conceptlz\AdobeSign\Laravel\AdobeSignManager;

AdobeSignManager::resolveUserKeyUsing(fn ($user) => 'team:'.$user->current_team_id);

signatureLevel(): Conceptlz\AdobeSign\Enum\SignatureLevel
qualifiedIssuers(): list<string>

signatureShortfalls(string $agreementId, ?SignatureLevel $required = null): list<string>GET /agreements/{id}, /members, /events

__call(string $method, array $arguments): mixed

Core builders in a Laravel app

The builders and resources are the core SDK's; this section shows how they meet Laravel's request, Storage and model layers. For every option, see the core pages on uploading, creating agreements and signing order.

Upload a file from a request

transientDocuments()->upload() accepts a path, an SplFileInfo, an open stream or a PSR-7 stream, and streams the body, so a 20 MB PDF is never held in memory. An UploadedFile lives at a temporary path like /tmp/phpA1b2C3, without an extension, so pass the original name and MIME type explicitly; Adobe uses the name to work out the file type.

$request->validate(['contract' => ['required', 'file', 'mimes:pdf', 'max:25600']]);

$file = $request->file('contract');
$documentId = $sign->transientDocuments()->upload(
    $file->getRealPath(),
    fileName: $file->getClientOriginalName(),
    mimeType: 'application/pdf',
);

A transient document is a short-lived upload. Use the id to create an agreement soon after, typically in the same request or job.

Upload from a Storage disk

For a PDF you generated earlier or keep on S3, pass a read stream. With a stream the SDK can't guess a name, so fileName is required:

use Illuminate\Support\Facades\Storage;

$stream = Storage::disk('s3')->readStream("contracts/{$contract->id}.pdf");

$documentId = $sign->transientDocuments()->upload(
    $stream,
    fileName: "{$contract->reference}.pdf",
    mimeType: 'application/pdf',
);

Create and send an agreement

Creating an agreement sends it: the default state is IN_PROCESS, so the first signer gets an email immediately. Signers who share an order() number sign in parallel; numbers must run 1, 2, 3 without gaps, which the builder checks before anything is sent.

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

final class SendContractForSignature
{
    public function __construct(private readonly AdobeSign $sign)
    {
    }

    public function __invoke(Contract $contract, string $documentId): string
    {
        $agreementId = $this->sign->agreements()->create(
            AgreementInfo::create($contract->title)
                ->file(FileInfo::transientDocument($documentId))
                ->externalId((string) $contract->id)          // find it again with agreements()->all(externalId: ...)
                ->participantSet(ParticipantSetInfo::signer(
                    ParticipantInfo::email($contract->client_email, $contract->client_name),
                )->order(1))
                ->participantSet(ParticipantSetInfo::signer('cfo@example.com')->order(2))
                ->participantSet(ParticipantSetInfo::signer('legal@example.com')->order(2))
                ->message('Please review and sign.'),
        );

        $contract->update(['adobe_agreement_id' => $agreementId, 'status' => 'sent']);

        return $agreementId;
    }
}

Track progress

Webhooks are the efficient way to follow an agreement (see Webhooks), but you can also ask:

$agreements = AdobeSign::agreements();

$agreements->status($id);                        // "OUT_FOR_SIGNATURE", "SIGNED", ...
$agreements->get($id)->isSigned();               // bool
$agreements->members($id, includeNextParticipantSet: true);   // raw array: who acted, whose turn it is
$agreements->signingUrlFor($id, 'client@example.com');         // embedded-signing link, or null if not their turn
$agreements->sendReminder($id, note: 'A gentle reminder.');    // reminds whoever's turn it is
$agreements->cancel($id, comment: 'Replaced by a new version.');

Right after creation Adobe is still processing the PDF: the status is DOCUMENTS_NOT_YET_PROCESSED for a few seconds and signingUrlFor() can throw NotFoundException (AGREEMENT_NOT_SIGNABLE). Answer with "try again shortly" rather than an error page, as the example controller does with a 409.

Stream the PDF to the browser

Downloads come back as PSR-7 streams. Copy them into a StreamedResponse in chunks:

use Symfony\Component\HttpFoundation\StreamedResponse;

public function download(string $agreementId, AdobeSign $sign): StreamedResponse
{
    $pdf = $sign->agreements()->combinedDocument($agreementId);

    return new StreamedResponse(function () use ($pdf) {
        while (! $pdf->eof()) {
            echo $pdf->read(65536);
        }
    }, 200, [
        'Content-Type' => 'application/pdf',
        'Content-Disposition' => 'attachment; filename="'.$agreementId.'.pdf"',
    ]);
}

To keep a copy, write it to a disk instead; the walkthrough's download job shows Storage::writeStream().

Turn SDK exceptions into HTTP responses

Every SDK exception implements Conceptlz\AdobeSign\Exception\AdobeSignException, and API errors carry $statusCode and Adobe's $errorCode. Map the ones users can do something about in bootstrap/app.php:

use Conceptlz\AdobeSign\Exception\{AccountCapabilityException, NotFoundException, OAuthException};
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(fn (OAuthException $e) => redirect()
        ->route('adobe-sign.oauth.redirect')
        ->with('status', 'Please reconnect your Acrobat Sign account.'));

    $exceptions->render(fn (AccountCapabilityException $e) => response()->json([
        'message' => 'Your Acrobat Sign plan does not allow this: '.$e->errorCode,
    ], 422));

    $exceptions->render(fn (NotFoundException $e) => response()->json([
        'message' => 'Agreement not found or not ready yet.',
    ], 404));
})

The core's errors page lists every exception class and when it is thrown.

Acting as another user: asUser()

With an account admin's Integration Key you can act on behalf of any user in the account. The SDK sends the x-api-user header; Adobe then treats that user as the sender, so the agreement appears in their Acrobat Sign account and emails come from them.

// Bare emails and ids are prefixed for you; "email:..." and "userid:..." are passed through.
$sales = AdobeSign::asUser('jane@example.com');

$sales->agreements()->create($info);
foreach ($sales->agreements()->all() as $summary) {
    // Jane's agreements
}

asUser() returns a new client; the original is unchanged, so it is safe to call from a shared client. It needs an admin-level key or token; when Adobe rejects the x-api-user header the SDK throws AuthenticationException. If each user has their own OAuth connection, prefer forUser(), which needs no admin rights.

Using the client in queued jobs

Anything slow (downloads, bulk sends, polling) belongs on a queue. Three rules keep jobs correct:

1. Serialise ids, not clients

   A client holds an HTTP pipeline and a token provider, which don't belong in a queue payload. Store the agreement id (and for OAuth, the user key) on the job, and resolve the client in handle().

2. For OAuth, name the user explicitly

   There is no signed-in user in a worker, so the default client fails in oauth mode. Pass the user key and call forUser().

3. Let the queue handle throttling

   The SDK already retries short Retry-After waits. For longer ones it throws RateLimitException with $retryAfter in seconds; release the job for that long instead of failing it.

use Conceptlz\AdobeSign\Exception\RateLimitException;
use Conceptlz\AdobeSign\Laravel\AdobeSignManager;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

final class SendReminderForUser implements ShouldQueue
{
    use Queueable;

    public int $tries = 5;

    public function __construct(
        public readonly int $userId,
        public readonly string $agreementId,
    ) {
    }

    public function handle(AdobeSignManager $adobe): void
    {
        try {
            $adobe->forUser($this->userId)
                ->agreements()
                ->sendReminder($this->agreementId, note: 'Just checking in on this one.');
        } catch (RateLimitException $e) {
            $this->release($e->retryAfter ?? 60);
        }
    }
}

Each job gets a fresh manager, so tokens refreshed in one job are re-read from the database by the next. Adobe doesn't rotate refresh tokens, so two workers refreshing the same user at the same moment both end up with valid access tokens; no locking is needed.

Common questions

• Walkthrough: send & storeThe full loop, from upload to signed PDF in storage.
• OAuthConnect user accounts and use forUser().