While using webhooks is the recommended standard for real-time automation in Circularo, there are many scenarios where you might prefer to “pull” information rather than wait for it to be “pushed.” 

Whether you are building a dashboard to track internal progress or running a cleanup script for stalled documents, knowing how to efficiently poll the Circularo API for document status is a key skill for any integrator.

Polling vs. Webhooks

In our previous posts, we focused on webhooks, where an event (like a signature) triggers an immediate notification to your server.

Polling, on the other hand, involves your server proactively asking Circularo: “What is the status of this document right now?”

Polling is ideal for:

• On-demand status checks: When a user refreshes their view in your application
• Scheduled reporting: Generating a daily summary of all pending signatures
• System synchronization: Ensuring your database matches the state in Circularo

Monitoring the Workflow

When you call the Get Document endpoint (GET /documents/{documentId}), Circularo returns a JSON object. To see exactly where the document sits in its journey, you should look specifically at the workflow object.

Two critical arrays inside this object help you monitor participant progress:

• workflow.alreadySigned: This array contains a list of recipients who have already completed their action (signing, approving, or stamping)
• workflow.waitingFor: Lists recipients who still have pending actions on the document. This could be both the currently active user and all people who will receive the document in the next workflow step(s)

Example

{
...
"workflow": {
  "waitingFor": [
                    {
                        "action": "sign",
                        "hasTurn": true,
                        "hasTurnSince": "2026-01-01T00:00:00.000Z",
                        "isMandatory": true,
                        "order": null,
                        "shareId": "gt5OLpwBPIL5-bCvWTAga",
                        "user": {
                            "name": "external@email.com",
                            "type": "external"
                        }
                    },
                    {
                        "action": "approve",
                        "hasTurn": false,
                        "hasTurnSince": "2026-01-01T00:00:00.000Z",
                        "isMandatory": true,
                        "order": null,
                        "shareId": "g77PHpwOLI5-bCvWTAga",
                        "user": {
                            "name": "user@internal.com",
                            "type": "internal"
                        }
                    }
],
   "alreadySigned": [
                    {
                        "action": "review",
                        "hasTurn": true,
                        "hasTurnSince": "2026-01-01T00:00:00.000Z",
                        "isMandatory": true,
                        "order": 2,
                        "shareId": "G7k_uloBYUTEy16j92Nj",
                        "user": {
                            "name": "reviewer@internal.com",
                            "type": "internal"
                        }
                    }
],
...
}

Note: In a sequential workflow, you can identify the currently active user by checking the hasTurn parameter. It will be true only for users who currently have the document in their inbox.

By monitoring these sections, you can build logic that sends custom reminders or updates your UI to show exactly whose signature is missing.

Understanding Document States

A document in Circularo moves through a specific set of states. Understanding these is vital for correctly interpreting the API response.

When using the Get Document endpoint (GET /documents/{documentId}), this value will be present in the workflow.shareStateName parameter.

Note: If the workflow has not yet started, the value will be blank (the workflow.shareStateName parameter will be missing)

The Audit Trail

If you need more than just the current status, you can call the Audit endpoint: 

POST logs/search
{
  "logsQuery": {
    "query": {
      "filter": [
        {
          "type": "term",  //Filter by activity target type (document)
          "field": "activityTarget",
          "value": "document"
        },
          {
          "type": "term",  //Filter by subject (document ID)
          "field": "subject",
          "value": "db7b21a7-f8b2-472e-be59-625102de6f92"
        }
      ]
    }
  }
}

This provides a legally binding chronological record of every action taken on the document, from the moment it was uploaded to the final signature.

Conclusion

Polling the Circularo API for document status is a meaningful alternative to webhooks.

In this article, we have explored the structure of the callback workflow object and how to identify the important parameters it provides to gather information about the document journey.

Use these API calls to build robust dashboards or synchronize your internal systems with Circularo status updates

In our next article, we’ll have a look at how to download a document once it has been fully signed and completed by all involved parties.