Retrieving documents

Almost everything you need to know to list or search for specific documents of a user.

Avoid using these methods to frequently check the status of signatures. Webhooks are a faster and more efficient way to do this (and our backend will thank you 😅 )

Retrieving a specific document

In Altair, you can test with the "Retrieve document" item from the pre-built collection. Don't forget to complete the query with the ID of an existing document to search.

# If you copy the query, remember to remove the comments

query {
  document(id: "DOCUMENT ID") {
    id
    name
    refusable
    sortable
    created_at
    files { original signed pades }
    signatures {
      public_id
      name
      email
      created_at
      action { name }
      link { short_link } # Signature link when the signer is added by "name" instead of "email"
      user { id name email phone }
      user_data { name email phone } # Data related to lock_user_data when creating the document
      email_events {
        sent # Email sending timestamp confirmation
        opened # Email open timestamp (may not be registered in some email clients)
        delivered # Email open timestamp (may not be registered in some email clients)
        refused # Email sending error timestamp
        reason # Error message returned when sending fails
      }
      viewed { ...event } # When the signer views
      signed { ...event } # When the signer signs
      rejected { ...event } # When the signer rejects
      signed_unapproved { ...event } # When the signer signs but is pending biometric approval
      biometric_approved { ...event } # When the pending biometric of the signer is approved
      biometric_rejected { ...event } # When the pending biometric of the signer is rejected
    }
  }
}

fragment event on Event {
  ip
  port
  reason
  created_at
  geolocation {
    country
    countryISO
    state
    stateISO
    city
    zipcode
    latitude
    longitude
  }
}

You may check the results straight in Altair:

Similarly, you can use fragments as a way to avoid repetition in queries with GraphQL.

You can also query multiple documents at once:

query {
  first: document(id: "DOCUMENT_ID_1") { name }
  second: document(id: "DOCUMENT_ID_2") { name }
  third: document(id: "DOCUMENT_ID_3") { name }
}

As shown in the image above, you can also name the queries. (Note: The name cannot contain only numbers).

Listing Documents

It is also possible to return pages containing multiple documents:

query {
  documents(limit: 60, page: 1) {
    total
    data {
      id
      name
      refusable
      sortable
      created_at
      signatures {
        public_id
        name
        email
        created_at
        action { name }
        link { short_link }
        user { id name email }
        viewed { created_at }
        signed { created_at }
        rejected { created_at }
      }
      files { original signed }
    }
  }
}

Retrieving documents from a folder

You can also retrieve the documents contained in a folder:

query{
  documentsByFolder(folder_id: "FOLDER_ID", limit: 60, page: 1) {
    data {
      id
      name
      qualified
      sandbox
      created_at
      deleted_at
    }
    has_more_pages
  }
}

The query itself is practically the same as listing documents, with the only difference being that you can specify a folder ID to perform the search. The information returned is also of the same type as the previous request.

You can check what each of these parameters means directly in the full GraphQL API documentation, in the Docs menu of Altair. If you're not sure how to do that, check out our tutorial on Using Altair.

If Altair doesn't help you integrate with the API, check out some examples of how to make these requests in other ways: https://graphql.org/graphql-js/graphql-clients/

19KB

Autentique v2.postman_collection.json

Open

Para importar e usar no Postman