Go to Parseur
All Collections
Controlling and managing data
Use Parseur document parsing API

Use Parseur document parsing API

How to use Parseur API to manage your documents and parsing workflow
Sylvestre avatar
Written by Sylvestre. Updated over a week ago

This article describes how to control your mailboxes via its native REST HTTPS API.

Notes:

Parseur API Authentication

Parseur API uses token-based authentication.

You will find your API Token Key in your Account Overview.

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with white space separating the two strings. For example:

Authorization: Token 1234d45678c90bcf1234fe123ddae4aabbc6abcd

Unauthenticated responses that are denied permission will result in an  HTTP 403 Unauthorized response with an appropriate WWW-Authenticate header. For example:

WWW-Authenticate: Token

The curl command line tool may be useful for testing token authenticated APIs. For example:

curl -X GET https://api.parseur.com/ -H "Authorization: Token <enter-your-token-here>"

Manage Mailboxes

List mailboxes

Mailboxes objects are called parsers in the API.

To list all your mailboxes, make a GET request on /parser. The response is paginated.

Supported sorting keys (see the section below for more information):

  • name

  • document_count

  • template_count

  • PARSEDOK_count (number of documents processed)

  • PARSEDKO_count (number of documents not processed)

  • QUOTAEXC_count (number of documents in quota exceeded status)

  • EXPORTKO_count (number of documents in export failed status)

The search query parameter will search in the following properties:

  • mailbox name

  • mailbox email prefix

Create a mailbox

To create a mailbox, make a POST request on /parser passing the following keys:

  • name

  • email_prefix (optional, if not present, will be derived from name key)

  • process_attachments: true / false (optional, defaults to true)

  • master_parser_slug: optional, set it if you want your mailbox to use one of our set of ready-made templates. Possible values are: search-alerts, food-delivery, real-estate, job-application, property-bookings, job-search.

Retrieve a mailbox

You can retrieve a mailbox with a GET request on /parser/:mailbox_id

Update a mailbox

You can update a mailbox with a PUT or POST request on /parser/:mailbox_id

Copy a mailbox

You can copy (duplicate) an existing mailbox with a POST on /parser/:mailbox_id/copy

Delete a mailbox

You can delete a mailbox with a DELETE request on /parser/:mailbox_id

Get the field structure (schema) of a mailbox

You can get the mailbox schema with a GET request on /parser/:mailbox_id/schema

Useful if you're planning to create a connector for Parseur.

Manage Documents in a mailbox

Send documents

To send a document via API, check out this article

List documents

You can list your documents in a given mailbox with a GET request on /parser/:mailbox_id/document_set. The response is paginated.

Supported sorting keys (see the section below for more information):

  • name

  • created (default - received date)

  • modified (processed date)

  • status

The search query parameter will search in the following properties:

  • document id (exact match)

  • document name

  • template name

  • from to, cc and bcc email addresses

  • document metadata header

Retrieve a document

You can retrieve a document and parsed results with a GET request on /document/:document_id

Update a document

You cannot update a document.

Reprocess a document

You can reprocess (parse) a document with a POST on /document/:document_id/process

Skip a document

You can set the Skipped status on a document with a POST on /document/:document_id/skip

Copy a document

You can copy a document to another mailbox with a POST on /document/:document_id/copy/:target_mailbox_id

Retrieve the logs for a document

You can access the activity logs of a document with a GET on /document/:document_id/log_set. Logs are paginated.

Delete a document

You can delete a document with a DELETE request on /document/:document_id

Manage Templates in a mailbox

List templates

You can list your templates in a given mailbox with a GET request on /parser/:mailbox_id/template_set. The response is paginated.

Supported sorting keys (see the section below for more information):

  • name

  • created (creation date)

  • modified (default - last template update time or last time template was used)

  • last_activity (last time template was used)

  • status

  • document_count (number of documents matched by the template)

The search query parameter will search in the following properties:

  • template name

Create a template

You need to use the template editor to create and update templates.

Retrieve a template

You can retrieve a template with a GET request on /template/:template_id

Copy a template

You can copy a template with a POST on /template/:template_id/copy/:target_mailbox_id

Delete a template

You can delete a template with a DELETE request on /template/:template_id

Manage Webhooks in a mailbox

List webhooks

You can list your webhooks in a given mailbox with a GET request on /parser/:mailbox_id

  • Enabled webhooks are under the webhook_set key

  • Paused webhooks are under the available_webhook_set key.

Create a webhook

You can create a new webhook with a POST request on /webhook passing the following keys:

  • event: must be one of document.processed, document.processed.flattened, document.template_needed or table.processed (see our webhook reference article for more information)

  • target: URL to send the data to, e.g. https://api.example.com/parseur

  • category: must be set to CUSTOM

  • parser: ID of the mailbox you want to add the webhook to, in numerical format

  • name: Custom name for the webhook. If omitted, will use the target URL instead. Optional

  • headers: JSON object containing the HTTP headers you want to send along with the result data. Optional

  • parser_field: ID of a field or a table field you want the webhook to react to, in the "PF12345" format

Enable a webhook

You can enable an existing webhook for a given mailbox with a POST request on /parser/:mailbox_id/webhook_set/:webhook_id

Pause a webhook

You can pause an existing webhook for a given mailbox with a DELETE request on /parser/:mailbox_id/webhook_set/:webhook_id

Manage parsed data

Parseur can send parsed data in real-time to your server via its Webhook feature. Check out the webhook article to learn more.

Optional HTTP Query parameters

The following query parameters can be mixed and matched.

Pagination

All GET request that return a list of documents, templates and mailboxes that support the pagination by appending a page option to the URL. The default page size is 25. You can change the page size using the page_size query parameter.

For example: /parser?page=2&page_size=50 will list the 2nd page of your mailboxes, each page containing 50 records.

Searching

Some endpoints support sorting via the search query parameter. The search value needs to be URL encoded.

For example /parser?search=test%20mailbox will search for mailbox names containing "test mailbox"

Unless stated otherwise, search is not case sensitive and will retrieve all entities that partially match the search string. For example, a mailbox search for foo will return mailboxes named test.foo and FOO Mailbox 123.

Sorting

Some endpoints support sorting via the ordering query parameter.

  • to sort a list ascending on the foo key, use ?ordering=foo

  • to sort a list descending on the foo key, use ?ordering=-foo

For example /parser?ordering=-document_count will list your mailboxes starting with the one with the most documents.

Do more with the API

This article just lists the most common use cases of using our API. There is more you can do, feel free to ask us for more details!

Did this answer your question?