Garrigues Signature Manager - Legal Entity Signers Operations

Introduction

A Legal Entity Signer represents a legal person (a company or other legal entity, identified by a tax ID) that signs a document instead of, or alongside, natural person signatories. Unlike signatories, legal entity signers are not notified: they are automatically signed by the platform when the signature request is activated (see Activate signature request).

A legal entity signer moves through the following statuses: PENDING → SIGNED. This transition happens automatically on activation and generates a technical evidence for the signature.

Every legal entity signer operation requires the signature request to be in DRAFT status, except for the list operations.

Operations

This endpoint retrieves a list of legal entity signers for a specific document.

HTTP Request

GET /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/legal-entity-signers

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
ids No array of string (UUID) Filter by legal entity signer IDs.
taxIds No array of string Filter by tax IDs.
roleTypes No array of string Filter by role type. Possible value: CONTRACT_ISSUER.
statuses No array of string Filter by status. Possible values: PENDING, SIGNED.
hasCoordinates No boolean Filter signers by whether they have coordinates.
page No integer Page number for pagination.
size No integer Number of items per page.
sort No array of string Sorting criteria in the format field:order (e.g., name:ASC, taxId:DESC).

Example Response

{
  "records": [
    {
      "id": "b7a16f42-8e65-4c6f-8253-ad6ded8ae666",
      "signatureRequestId": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
      "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
      "name": "Acme Corp S.L.",
      "taxId": "B12345678",
      "roleType": "CONTRACT_ISSUER",
      "status": "PENDING",
      "signedAt": null,
      "metadata": {
        "department": "legal"
      },
      "coordinates": [
        {
          "x": 100.5,
          "y": 200.75,
          "page": 1
        }
      ]
    }
  ],
  "_metadata": {
    "currentPage": 0,
    "totalPages": 1,
    "pageSize": 20,
    "totalRecords": 1
  }
}

Error: 400 Bad request | 500 Unexpected error

This endpoint retrieves a list of legal entity signers across all documents of a signature request.

HTTP Request

GET /api/v1/private/signature-requests/{signatureRequestId}/legal-entity-signers

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId No string (UUID) Filter by document.
ids No array of string (UUID) Filter by legal entity signer IDs.
taxIds No array of string Filter by tax IDs.
roleTypes No array of string Filter by role type. Possible value: CONTRACT_ISSUER.
statuses No array of string Filter by status. Possible values: PENDING, SIGNED.
hasCoordinates No boolean Filter signers by whether they have coordinates.
page No integer Page number for pagination.
size No integer Number of items per page.
sort No array of string Sorting criteria in the format field:order (e.g., name:ASC, taxId:DESC).

Error: 400 Bad request | 500 Unexpected error

This endpoint adds a legal entity signer to a document.

HTTP Request

POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/legal-entity-signers

Example Request Body

{
  "name": "Acme Corp S.L.",
  "taxId": "B12345678",
  "roleType": "CONTRACT_ISSUER",
  "metadata": {
    "department": "legal"
  },
  "coordinates": [
    {
      "x": 100.5,
      "y": 200.75,
      "page": 1
    }
  ]
}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
name Yes string Legal entity name.
taxId Yes string Legal entity tax identifier.
roleType Yes string Role of the legal entity signer. Possible value: CONTRACT_ISSUER.
metadata No object (map of string to string) Free-form key/value metadata.
coordinates No array of objects Signature coordinates.
coordinates[].x Yes (if provided) number Horizontal position.
coordinates[].y Yes (if provided) number Vertical position.
coordinates[].page Yes (if provided) integer Page number.

Example Response

{
  "id": "b7a16f42-8e65-4c6f-8253-ad6ded8ae666",
  "signatureRequestId": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
  "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
  "name": "Acme Corp S.L.",
  "taxId": "B12345678",
  "roleType": "CONTRACT_ISSUER",
  "status": "PENDING",
  "signedAt": null,
  "metadata": {
    "department": "legal"
  },
  "coordinates": [
    {
      "x": 100.5,
      "y": 200.75,
      "page": 1
    }
  ]
}

Error: 400 Bad request | 404 Signature request or document not found | 409 Signature request status should be draft or document in invalid status | 500 Unexpected error

This endpoint updates a legal entity signer. Unlike other participant update operations in this API (which use PATCH), this is the only PUT endpoint of the service: the fields provided replace the corresponding fields of the existing legal entity signer.

HTTP Request

PUT /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/legal-entity-signers/{legalEntitySignerId}

Example Request Body

{
  "name": "Acme Corp S.L.U.",
  "taxId": "B12345678",
  "roleType": "CONTRACT_ISSUER",
  "metadata": {
    "department": "legal"
  },
  "coordinates": [
    {
      "x": 120,
      "y": 220,
      "page": 1
    }
  ]
}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
legalEntitySignerId Yes string (UUID) Unique identifier for the legal entity signer.
name No string Updated legal entity name.
taxId No string Updated tax identifier.
roleType No string Updated role type. Possible value: CONTRACT_ISSUER.
metadata No object (map of string to string) Updated metadata.
coordinates No array of objects Updated signature coordinates.
coordinates[].x Yes (if provided) number Horizontal position.
coordinates[].y Yes (if provided) number Vertical position.
coordinates[].page Yes (if provided) integer Page number.

Example Response

{
  "id": "b7a16f42-8e65-4c6f-8253-ad6ded8ae666",
  "signatureRequestId": "6db10639-bfd1-4a0a-bf2b-e837b715c0c8",
  "documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
  "name": "Acme Corp S.L.U.",
  "taxId": "B12345678",
  "roleType": "CONTRACT_ISSUER",
  "status": "PENDING",
  "signedAt": null,
  "metadata": {
    "department": "legal"
  },
  "coordinates": [
    {
      "x": 120,
      "y": 220,
      "page": 1
    }
  ]
}

Error: 400 Bad request | 404 Legal entity signer not found | 409 Signature request status should be draft | 500 Unexpected error

This endpoint deletes a legal entity signer from a document.

HTTP Request

DELETE /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/legal-entity-signers/{legalEntitySignerId}

Where

Parameter Mandatory Datatype Description
signatureRequestId Yes string (UUID) Unique identifier for the signature request.
documentId Yes string (UUID) Unique identifier for the document.
legalEntitySignerId Yes string (UUID) Unique identifier for the legal entity signer.

Error: 400 Bad request | 404 Legal entity signer not found | 409 Signature request status should be draft or signer already signed | 500 Unexpected error