Get signing request — Brigg developers

Access & visibility

Allow signing.GetSigningRequest on your API key.

Workspace access by default. Private member data requires approved member delegation through Brigg-Act-As; the key supplies permissions while private ownership and project boundaries remain enforced.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

signing_request_idstringRequired

Keep the signing_request_id returned when invitations were requested. A file_id or signer_id identifies something else. signing.RequestFileSignatures.

At least 1 character.

Follow one signing request through completion

Upload a readable PDF, then request signatures and keep signing_request_id. The request keeps a fixed source; replacing the original file later does not change what recipients sign.

Read Get signing request for per-recipient progress. completed means everyone signed, but the archive can still be preparing: wait for non-null file_id before requesting the signed PDF. Get signing document returns a short-lived URL for either the fixed original or the signed archive.

Notification failures do not undo the signing request. Remind the affected pending recipients instead of creating a duplicate request. Recipients sign themselves; a delegated API call cannot supply a recipient's signature. See the complete signing workflow.

Response

Returns 200 OK with a JSON body.

signing_request_idstringRequired

Signing request identifier.

titlestringRequired

Display title.

statusstringRequired

Request state: pending is awaiting signatures; completed means every recipient signed; cancelled stops the request; expired means a pending request passed its deadline. Completed does not by itself guarantee an archived file.

Allowed: "pending", "completed", "cancelled", "expired".

signature_methodstringRequired

Signature method required for the request.

Allowed: "standard", "bankid".

expires_atnumberRequired

Signing deadline in Unix milliseconds.

created_atnumberRequired

Creation time in Unix milliseconds.

completed_atnumber or nullRequired

Time signing completed, in Unix milliseconds, or null while incomplete.

sourceobjectRequired

Original document identity preserved for this signing request.

Nested fields

typestringRequired

Type identifying which variant of this model applies.

Allowed: "file", "document", "registration".

idstringRequired

Original identity, interpreted with source.type: file means the uploaded file_id, document means the generated document_id, and registration means the business registration_id. It is not the signed archive's file_id.

sha256stringOptional

SHA-256 hex digest of the fixed uploaded PDF source, when included. Replacing the original file does not change that signing source.

file_idstring or nullRequired

Signed archive identity, or null when not yet available. Request version=signed from GetSigningDocument only after this is present.

signersarray of objectRequired

Named recipients and their individual signature states.

Item fields

signer_idstringRequired

Signer identifier.

emailstringRequired

Email address.

namestring or nullRequired

Display name.

statusstringRequired

This recipient's state: pending has not signed, signed completed their signature, declined refused. It is independent of archive creation and is not the request's overall state.

Allowed: "pending", "signed", "declined".

signed_atnumber or nullRequired

Unix millisecond time of this recipient's signature, or null if they have not signed.

Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. If Brigg-Act-As is supplied, the key must be authorized to delegate to that member.
404	`not_found`	The request is unavailable to this identity. A workspace-only credential can read its own initiated requests; member delegation also checks that member's signing access.
429	`rate_limited`	Wait for Retry-After before retrying.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "signing_request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Keep the signing_request_id returned when invitations were requested. A file_id or signer_id identifies something else. [signing.RequestFileSignatures](/developers/reference/signing/RequestFileSignatures)."
    }
  },
  "required": [
    "signing_request_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "signing_request_id": "sig_project_agreement"
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "signing_request_id": {
      "type": "string",
      "description": "Signing request identifier."
    },
    "title": {
      "type": "string",
      "description": "Display title."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "completed",
        "cancelled",
        "expired"
      ],
      "description": "Request state: pending is awaiting signatures; completed means every recipient signed; cancelled stops the request; expired means a pending request passed its deadline. Completed does not by itself guarantee an archived file."
    },
    "signature_method": {
      "type": "string",
      "enum": [
        "standard",
        "bankid"
      ],
      "description": "Signature method required for the request."
    },
    "expires_at": {
      "type": "number",
      "description": "Signing deadline in Unix milliseconds."
    },
    "created_at": {
      "type": "number",
      "description": "Creation time in Unix milliseconds."
    },
    "completed_at": {
      "type": [
        "number",
        "null"
      ],
      "description": "Time signing completed, in Unix milliseconds, or null while incomplete."
    },
    "source": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "file",
            "document",
            "registration"
          ],
          "description": "Type identifying which variant of this model applies."
        },
        "id": {
          "type": "string",
          "description": "Original identity, interpreted with source.type: file means the uploaded file_id, document means the generated document_id, and registration means the business registration_id. It is not the signed archive's file_id."
        },
        "sha256": {
          "type": "string",
          "description": "SHA-256 hex digest of the fixed uploaded PDF source, when included. Replacing the original file does not change that signing source."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false,
      "description": "Original document identity preserved for this signing request."
    },
    "file_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Signed archive identity, or null when not yet available. Request version=signed from GetSigningDocument only after this is present."
    },
    "signers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "signer_id": {
            "type": "string",
            "description": "Signer identifier."
          },
          "email": {
            "type": "string",
            "description": "Email address."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "signed",
              "declined"
            ],
            "description": "This recipient's state: pending has not signed, signed completed their signature, declined refused. It is independent of archive creation and is not the request's overall state."
          },
          "signed_at": {
            "type": [
              "number",
              "null"
            ],
            "description": "Unix millisecond time of this recipient's signature, or null if they have not signed."
          }
        },
        "required": [
          "signer_id",
          "email",
          "name",
          "status",
          "signed_at"
        ],
        "additionalProperties": false
      },
      "description": "Named recipients and their individual signature states."
    }
  },
  "required": [
    "signing_request_id",
    "title",
    "status",
    "signature_method",
    "expires_at",
    "created_at",
    "completed_at",
    "source",
    "file_id",
    "signers"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "signing_request_id": "sig_project_agreement",
      "title": "Project agreement",
      "status": "pending",
      "signature_method": "standard",
      "expires_at": 1794906000000,
      "created_at": 1794301200000,
      "completed_at": null,
      "source": {
        "type": "file",
        "id": "f_agreement",
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "file_id": null,
      "signers": [
        {
          "signer_id": "signer_jamie",
          "email": "jamie@example.com",
          "name": "Jamie Lee",
          "status": "pending",
          "signed_at": null
        }
      ]
    }
  ]
}

Try the request

Use your API key in a server environment.

Example scenarioAct as a memberRequires administrator-approved delegation.

The source PDF and future signed archive have distinct identities.

Request

cURL

curl 'https://api.brigg.app/v1/operations/signing.GetSigningRequest' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "signing_request_id": "sig_project_agreement"
}'

TypeScript

const response = await fetch("https://api.brigg.app/v1/operations/signing.GetSigningRequest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "signing_request_id": "sig_project_agreement"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "signing_request_id": "sig_project_agreement"
}
request = Request(
    "https://api.brigg.app/v1/operations/signing.GetSigningRequest",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

cURL

curl 'https://api.brigg.app/v1/operations/signing.GetSigningRequest' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "signing_request_id": "sig_project_agreement"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/signing.GetSigningRequest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "signing_request_id": "sig_project_agreement"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "signing_request_id": "sig_project_agreement"
}
request = Request(
    "https://api.brigg.app/v1/operations/signing.GetSigningRequest",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "signing_request_id": "sig_project_agreement",
  "title": "Project agreement",
  "status": "pending",
  "signature_method": "standard",
  "expires_at": 1794906000000,
  "created_at": 1794301200000,
  "completed_at": null,
  "source": {
    "type": "file",
    "id": "f_agreement",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "file_id": null,
  "signers": [
    {
      "signer_id": "signer_jamie",
      "email": "jamie@example.com",
      "name": "Jamie Lee",
      "status": "pending",
      "signed_at": null
    }
  ]
}

Illustrative values, not a live response.

Download the signed version through GetSigningDocument.

Request

cURL

curl 'https://api.brigg.app/v1/operations/signing.GetSigningRequest' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "signing_request_id": "sig_project_agreement"
}'

TypeScript

const response = await fetch("https://api.brigg.app/v1/operations/signing.GetSigningRequest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "signing_request_id": "sig_project_agreement"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "signing_request_id": "sig_project_agreement"
}
request = Request(
    "https://api.brigg.app/v1/operations/signing.GetSigningRequest",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

cURL

curl 'https://api.brigg.app/v1/operations/signing.GetSigningRequest' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "signing_request_id": "sig_project_agreement"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/signing.GetSigningRequest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "signing_request_id": "sig_project_agreement"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "signing_request_id": "sig_project_agreement"
}
request = Request(
    "https://api.brigg.app/v1/operations/signing.GetSigningRequest",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "signing_request_id": "sig_project_agreement",
  "title": "Project agreement",
  "status": "completed",
  "signature_method": "standard",
  "expires_at": 1794906000000,
  "created_at": 1794301200000,
  "completed_at": 1794304800000,
  "source": {
    "type": "file",
    "id": "f_agreement",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "file_id": "f_signed_agreement",
  "signers": [
    {
      "signer_id": "signer_jamie",
      "email": "jamie@example.com",
      "name": "Jamie Lee",
      "status": "signed",
      "signed_at": 1794304800000
    }
  ]
}

Illustrative values, not a live response.

Wait and re-read. FinalizeSigning can recover an interrupted archive step; never substitute the original for the signed result.

Request

cURL

curl 'https://api.brigg.app/v1/operations/signing.GetSigningRequest' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "signing_request_id": "sig_project_agreement"
}'

TypeScript

const response = await fetch("https://api.brigg.app/v1/operations/signing.GetSigningRequest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "signing_request_id": "sig_project_agreement"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "signing_request_id": "sig_project_agreement"
}
request = Request(
    "https://api.brigg.app/v1/operations/signing.GetSigningRequest",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

cURL

curl 'https://api.brigg.app/v1/operations/signing.GetSigningRequest' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "signing_request_id": "sig_project_agreement"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/signing.GetSigningRequest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "signing_request_id": "sig_project_agreement"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "signing_request_id": "sig_project_agreement"
}
request = Request(
    "https://api.brigg.app/v1/operations/signing.GetSigningRequest",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "signing_request_id": "sig_project_agreement",
  "title": "Project agreement",
  "status": "completed",
  "signature_method": "standard",
  "expires_at": 1794906000000,
  "created_at": 1794301200000,
  "completed_at": 1794304800000,
  "source": {
    "type": "file",
    "id": "f_agreement",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "file_id": null,
  "signers": [
    {
      "signer_id": "signer_jamie",
      "email": "jamie@example.com",
      "name": "Jamie Lee",
      "status": "signed",
      "signed_at": 1794304800000
    }
  ]
}

Illustrative values, not a live response.