Overview

This node integrates with the ZapSign API to perform various document, signer, template, webhook, partnership, timestamp, and background check operations. Specifically for the Background Check resource with the Create Person Check operation, it allows users to initiate a background check on an individual by providing their CPF (Brazilian personal tax ID), optionally including their full name and an external identifier. The node can either create a new check or return an existing one based on the "Force Creation" flag.

Common scenarios:

• Verifying the background of a person before hiring or onboarding.
• Automating background verification workflows in HR or compliance processes.
• Integrating background checks into broader automation pipelines that require identity validation.

Practical example:
You want to automatically trigger a background check for a job applicant by providing their CPF and optionally their name. If a previous check exists, you can choose to reuse it or force a new check creation.

Properties

Output

The node outputs an array of JSON objects representing the response from the ZapSign API for each processed item. For the Create Person Check operation, the output JSON contains details about the created or retrieved background check, such as status, tokens, and any relevant metadata returned by the API.

No binary data output is produced by this operation.

Dependencies

• Requires an API key credential for authenticating with the ZapSign API.
• Uses environment variables to determine the base URL for the API:
  • ZAPSIGN_API_BASE_URL_SANDBOX (default fallback: https://sandbox.api.zapsign.com.br)
  • ZAPSIGN_API_BASE_URL (default fallback: https://api.zapsign.com.br)
• The node depends on internal helper functions for making HTTP requests and mapping data structures.

Troubleshooting

Common issues:

• 404 Not Found Error:
  Indicates that the Background Check feature may not be available on your ZapSign account. Possible reasons include:

  • Your plan does not include background checks.
  • You lack necessary permissions or need an account upgrade.
  • The API endpoint has changed or been deprecated.
  • The check token provided is invalid or expired.

  Resolution: Contact ZapSign support to verify feature availability and permissions.

• Invalid Input Errors:
  Ensure the CPF is correctly formatted and provided. Optional fields like name and external ID should be valid strings if used.

• API Authentication Issues:
  Make sure the API key credential is correctly configured and has access to the background check endpoints.

Error messages:

• Background Check feature not available (404 error):
  See above troubleshooting for 404 errors related to background checks.

• Other HTTP errors:
  The node logs detailed request and error information. Review these logs to identify issues such as malformed requests or network problems.

Links and References

• ZapSign API Documentation (general reference for API endpoints and parameters)
• ZapSign Background Check API (specific section for background check features)
• n8n documentation on Creating Custom Nodes

Summary of execute() logic for Resource: Background Check, Operation: Create Person Check

• Retrieves input parameters: personCpf (required), personName (optional), bcExternalId (optional), and forceCreation (boolean).
• Constructs a POST request body with:
  • user_authorized: true
  • force_creation set per input
  • type: "person"
  • country: "BR"
  • national_id set to the CPF
  • If name is provided, splits it into first and last names.
  • If external ID is provided, adds it as custom_input.
• Sends the POST request to ${baseUrl}/api/v1/checks/.
• On success, pushes the API response to the output array.
• On failure, handles errors gracefully, especially 404 errors indicating feature unavailability.
• Returns all results as JSON array output.

This operation enables automated creation or retrieval of person background checks via ZapSign within n8n workflows.