Skip to content

Industries

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.

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 and Captures.
  • delivery_type: "none". SignatureAPI does not email the signed documents to the provider. Your app shows or stores them. See Signer.
  • Tenant metadata. tenant_id and provider_id let a webhook handler find the right marketplace tenant. See 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 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, Ceremony events and the embedded signing guide.

Webhooks to listen for

  • envelope.started: the envelope is in_progress, so you can create the ceremony.
  • recipient.completed: 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: 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.

Default
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"
    }
  ]
}
{
  "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
}

Errors every call can return are in Errors and Authentication.