---
title: "Sign Provider Agreements During Signup"
description: "Create a provider agreement envelope in your marketplace, then show the signing ceremony in your app and send the provider to the next onboarding step."
canonical: "https://signatureapi.com/docs/use-cases/marketplace-providers"
source: "https://signatureapi.com/docs/use-cases/marketplace-providers.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:55Z"
---

# Sign Provider Agreements During Signup

Create a provider agreement envelope in your marketplace, then show the signing ceremony in your app and send the provider to the next onboarding step.

_Last verified against API version 1.18.0._

A provider who must leave your app for an email, sign, and come back often never returns. Instead, keep the provider in your onboarding flow. Your server creates the envelope and then a ceremony. The provider signs in an iframe, and your page moves them to the next step when signing ends.

## Envelope shape

- **One PDF with two places.** A `text_input` place asks for the business name, and a `signature` place belongs to the same `provider` recipient. `capture_as: business_name` stores the typed value in `captures`. See [Text input](https://signatureapi.com/docs/api/resources/places/text-input) and [Captures](https://signatureapi.com/docs/api/resources/envelopes/captures).
- **`delivery_type: "none"`.** SignatureAPI does not email the signed documents to the provider. Your app shows or stores them. See [Signer](https://signatureapi.com/docs/api/resources/recipients/signer).
- **Tenant metadata.** `tenant_id` and `provider_id` let a webhook handler find the right marketplace tenant. See [Metadata](https://signatureapi.com/docs/api/resources/envelopes/metadata).

## Routing

There is one signer, so the envelope uses the default `sequential` routing. The text input is a form place, and form places need sequential routing.

The envelope does not set a `ceremony`. Once it is `in_progress`, call [`POST /v1/recipients/{recipient_id}/ceremonies`](https://signatureapi.com/docs/api/resources/ceremonies/create) with `custom` authentication, which returns the ceremony `url`. Creating a ceremony revokes any previous active one for the recipient. Set `embeddable_in` to the origins that may frame it. Set `redirect_delay` between 0 and 20 seconds: for an embedded ceremony it is the delay before the completion event, after which your page moves the provider to the next onboarding step. See [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url), [Ceremony events](https://signatureapi.com/docs/embedded/ceremony-events) and the [embedded signing guide](https://signatureapi.com/docs/embedded/web-app).

## Webhooks to listen for

- [`envelope.started`](https://signatureapi.com/docs/api/resources/events/envelope-events): the envelope is `in_progress`, so you can create the ceremony.
- [`recipient.completed`](https://signatureapi.com/docs/api/resources/events/recipient-events): the provider signed. Read `envelope_metadata.tenant_id` to update the right tenant. Confirm the result here, not only from the browser message.
- [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events): the signed agreement and audit log are ready to download and attach to the provider record.

## Compliance notes

This is general information, not legal advice. Whether an electronic signature is valid for a provider agreement depends on your jurisdiction and the type of agreement, so have counsel review your terms and process. The ceremony URL is a bearer credential: anyone who has it can open the ceremony. Create it on your server, show it only to the signed-in provider, and keep personal data out of `metadata`.

### Example: Default

Provider Agreement (sample).

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Provider Agreement (sample)",
  "metadata": {
    "tenant_id": "tenant_abc123",
    "provider_id": "prov_204"
  },
  "topics": [
    "marketplace",
    "provider_onboarding"
  ],
  "documents": [
    {
      "key": "provider_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "business_name",
          "page": 1,
          "top": 140,
          "left": 210
        },
        {
          "place_key": "provider_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "business_name",
          "type": "text_input",
          "recipient_key": "provider",
          "prompt": "Business name",
          "width": 220,
          "capture_as": "business_name"
        },
        {
          "key": "provider_signature",
          "type": "signature",
          "recipient_key": "provider"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "provider",
      "name": "Maria Garcia",
      "email": "maria.garcia@example.com",
      "delivery_type": "none"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Provider Agreement (sample)",
  "label": null,
  "message": null,
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_HVl3Nj7XzTzX7jN3lVH5vn",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "provider_agreement"
    ]
  },
  "metadata": {
    "tenant_id": "tenant_abc123",
    "provider_id": "prov_204"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {
    "business_name": null
  },
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "provider_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 140,
          "left": 210,
          "place_key": "business_name"
        },
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "provider_signature"
        }
      ],
      "places": [
        {
          "key": "business_name",
          "type": "text_input",
          "recipient_key": "provider",
          "capture_as": "business_name",
          "hint": null,
          "format": null,
          "prompt": "Business name",
          "requirement": "required",
          "format_message": null,
          "font_size": 12,
          "width": 220
        },
        {
          "key": "provider_signature",
          "type": "signature",
          "recipient_key": "provider",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "provider",
      "email": "maria.garcia@example.com",
      "name": "Maria Garcia",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "none",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "marketplace",
    "provider_onboarding"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors.",
  "errors": [
    "recipients[0].email must be a valid email address"
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
