{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"24903f28-3c81-4a22-a284-8f2c149ef6a0","name":"Parashift Platform API v2","description":"# Getting Started\n\nTo get started with our API, we provide comprehensive documentation on how to consume our API. Our API implementation follows the [JSON API Standard](https://jsonapi.org/). We suggest to have a look at that first, if you are unfamiliar with that.\n\n## Making requests - in a nutshell\n\nAll requests you send to our API follow the same schema, with all the resulting \"resources\" having a `type`, `id`, `attributes` and `relationships`. For instance a document resource will have `type: \"documents\"`, its own `id` , and document-resource specific `attributes` and `relationships` as detailed below in the respective sections.\n\nA resource can always be requested by its `id`, if you know it, i.e. `api/v2/documents/123456`. Such a request returns one result (or a `Not Found`).\n\nWhen requesting resources, you can alternatively pass in a `filter`. For instance `api/v2/files?filter[file_type]=input_file&filter[batch_id]=123456` will give you the input files of a certain batch. Such requests return zero or more results.\n\nYou can also `include` related resources (from the `relationships`). For instance `api/v2/batches/123456?include=input_files` . In this case, you receive the one batch plus its input files `included`.\n\nWhich strategy is better when requesting related resources, `filter` or `include`, depends on your situation. For instance, `filter` can use pagination while `include` can not. Request by `id` will be quick, but you may need to `include` more if your really interested in some `related` resources, which may be slower.\n\nOne strategy may be faster than the other. Try both during development of your integration!\n\nUsing `include` too much may result in massive payloads, so is generally to be avoided.\n\n### Get your access key (API Key)\n\nTo authenticate against our API you need to submit a _Bearer Token_ with your requests. To get started you need an account on our platform.\n\n[https://app.parashift.io](https://app.parashift.io)\n\nThe Parashift App is divided into individual tenants, which are identified by the tenant_id. 1-n API keys can be defined for each tenant.\n\nAfter signing in, you can create API keys in the `Developer` / `API Keys` module.\n\n[See: Managing API Keys](https://app.parashift.io/pdc/%7B%7Btenant_id%7D%7D/api/api-keys/list)\n\n[More information: Postman Bearer Token](https://learning.postman.com/docs/sending-requests/authorization/authorization-types/#bearer-token)\n\n### Add request headers\n\nDon't forget to add these headers for every request you submit to the API.\n\n| Key | Value | **Value Example** |\n| --- | --- | --- |\n| Content-Type | application/vnd.api+json | application/vnd.api+json |\n| Authorization | Bearer \\[Your API Token\\] | Bearer GetYourOwnApiKeyInTheParashiftPlatformUrlAppDotParasfhiftDotIoThenNavigateInTheLeftHandMenuToDeveloperToApiKey |\n\n### Submit a request to our API\n\nIf you want to talk to our Parashift Platform API, use the following base URL and choose one of the documented requests.\n\nBase URL: `https://api.parashift.io/v2/`\n\ne.g.\n\n| verb | request |\n| --- | --- |\n| GET | [List Documents](https://docs.parashift.io/#c2a0e890-e03c-41cb-b7ab-a4fed84625e7) |\n| GET | [Show Document](https://docs.parashift.io/#14ef484a-e79e-46ee-b687-08a71d4a4510) |\n| POST | [Create Document](https://docs.parashift.io/#eb54a4ef-dafa-47b5-b241-199fccbd4c77) |\n\n# Error Handling\n\nOur API's follow the jsonapi standard to a large extend. The following status codes are issued as a response to your API requests.\n\n## HTTP Status Codes\n\n| Status Code | Description |\n| --- | --- |\n| 200 | Success |\n| 201 | Created. A resource has been added. |\n| 204 | No content.  <br>This is a common case when deleting records. |\n| 401 | Not authenticated.  <br>Did you submit a valid authorization token? |\n| 403 | Not authorized.  <br>You are authenticated, but have no access to the requested resource. |\n| 404 | Not found. The resource you are requesting is not available. |\n| 406 | Unknown Format.  <br>Did you provide the correct mime/content type?  <br>(Header: Content-Type=application/vnd.api+json) |\n| 422 | Unprocessable.  <br>You provided data, which can not be processed.  <br>Maybe mandatory fields are missing? |\n| 500 | Server Error.  <br>An unexpected condition was encountered and we have been notified already. |\n| 503 | The service is in maintenance mode. |\n\n# Pagination, search & filter\n\n## Pagination\n\nA collection potentially consists of a large amount of resources. To cope with that the result set can be paginated.\n\n### Limitations and Defaults\n\n- The default page size is 20.\n    \n- The maximum page size is 200.\n    \n\n### Paging a collection\n\n| Attribute | Notes |\n| --- | --- |\n| page\\[size\\]=150 | Sets the page size to 150. |\n| page\\[number\\]=2 | Selects page number 2.  <br>Hint: pagination starts with 1. 0 is an \"alias\". The results from page 1 are also received here. |\n| stats\\[total\\]=count | Returns the total number of records, based on which you can calculate the total number of pages. |\n\n### Example\n\nAssume the hypothetical resource \"documents\" and you want a page size of 10 and select page 2, the request would look like this:\n\n```\nGET /v2/documents?page[size]=10&page[number]=2&stats[total]=count\n\n ```\n\nNote that in the above example the answer will also include the total number of records by virtue of `stats[total]=count`.\n\n## Search and filter\n\nOn any collection endpoint, there is a certain set of filters enabled by default. Depending on the endpoint, there might be additional filters available, which will be specifically documented in these cases.\n\n## Filter collections\n\nIn all cases, _ATTRIBUTENAME_ is a placeholder for the specific field name. Example: A not filter for a field named _title_ would be described as _ATTRIBUTENAME_not_ and would result in _title_not_. Multiple filters can be added to the same request.\n\n### Filters for all available fields\n\n| Name | Example | Notes |\n| --- | --- | --- |\n| equals | filter\\[ATTRIBUTENAME\\]=value | This filters for items with exact matching of the given value. |\n| not equals | filter\\[ATTRIBUTENAME_not\\]=value | This filters for items which to not match the given value. |\n| empty | filter\\[ATTRIBUTENAME_blank\\]=true | Filters for empty fields. |\n| filled | filter\\[ATTRIBUTENAME_blank\\]=false | Filters for filled fields. |\n\n### Filters for text fields\n\n| Name | Example | Notes |\n| --- | --- | --- |\n| contains | filter\\[ATTRIBUTENAME_contains\\]=value | Search for parts of a string. |\n| , | filter\\[ATTRIBUTENAME\\]=value1,value2 | Search for different values (OR) |\n\n### Filters for integer and date fields\n\n| Name | Example | Notes |\n| --- | --- | --- |\n| less than | filter\\[ATTRIBUTENAME_lt\\]=value | Return any record less than the given value. |\n| less than or equal | filter\\[ATTRIBUTENAME_lte\\]=value | Return any record less than or equal to the given value. |\n| greater than | filter\\[ATTRIBUTENAME_gt\\]=value | Return any record greater than the given value. |\n| greater than or equal | filter\\[ATTRIBUTENAME_gte\\]=value | Return any record greater than or equal to the given value. |\n| range | filter\\[ATTRIBUTENAME_range\\]=value..value | Return any record between the given values. The format for the values is: `FROM..TO` where FROM and TO are the given values. |\n\n### Examples\n\n#### Filter by status\n\nHaving a theoretical resource called document and we want to filter for all documents with status _pending_, the result would look like this:\n\n```\nGET /v2/documents?filter[status]=pending\n\n ```\n\n#### Filter documents by status and a date range\n\nHaving a theoretical resource called document and we want to filter for all documents with status _pending_ and a certain _date range_, the result would look like this:\n\n```\nGET /v2/documents?filter[status]=pending&filter[created_at_range]=2020-07-01..2020-08-01\n\n ```\n\n#### Filter documents by status and query page 2\n\nHaving a theoretical resource called document and we want to filter for all documents with status _pending_ and query _page 2_, the result would look like this:\n\n```\nGET /v2/documents?filter[status]=pending&page[number]=2\n\n ```\n\n# Uploading documents / files\n\n## Limits and prerequisites\n\nThere are some limitations to the files uploaded to the API.\n\n- delivery: base64 encoded string\n    \n- mime type, automated processing: pdf, jpg, png or tiff\n    \n- mime type, manual processing: any, must be configured in upload configuration\n    \n- maximum page count: 500\n    \n- minimum file size: 100 bytes (anything smaller and we assume something went wrong)\n    \n- maximum file size: 20 MB\n    \n\n# Custom fields & External Identifier\n\n## What are custom fields & the external identifier for?\n\nIn some cases it is desirable to provide meta data together with requests for later processing. A usual use case would be to add an external document id or other correlation id from a third party system to match returned requests to their original source.\n\nTo this end you can pass along your custom fields to the Parashift platform rather than tracking the id of the document in your system. The custom fields are passed along through the whole process and will be available on every documents endpoint.\n\nUsually integrators use the Parashift document identifier (id) to keep track of uploaded documents, match processed/documents against documents and query documents. To this end the custom_fields cannot be used as they are not searchable. The external_id, even though searchable and therefore suited for this, performs worse then the Parashift document id and should only be used if the Parashift document id can not be saved/tracked in the to be integrated system.\n\n## Custom field vs. External Identifier vs. Parashift document Identifier\n\n|  | custom_fields | external_id | id |\n| --- | --- | --- | --- |\n| set by / when | integrator, on upload | integrator, on upload | Parashift, on upload |\n| data type | string | string | string |\n| Searchable | no  <br>custom_fields are not indexed and cannot be queried, they are merely passed along. | yes  <br>indexed and can be queried.  <br>We still recommend using our Parashift document ID where possible | Yes  <br>indexed and can be queried, generally performs better then the external_id |\n| Unique | no | no | yes |\n| Amount | up to 5 | 1 | 1 |\n\n## How to use custom fields?\n\nYou can just pass along a hash of custom fields via the _custom_field_ attribute when [submitting documents](https://docs.parashift.io/#eb54a4ef-dafa-47b5-b241-199fccbd4c77):\n\n``` json\n{\n    \"data\": {\n        \"type\": \"documents\",\n        \"attributes\": {\n            ...\n            \"custom_fields\": {\n                \"customer_id\": \"1234\",\n                \"my_own_document_id\": \"EX12345678910\"\n            }\n            ...\n        }\n    }\n}\n\n ```\n\nAny following request to that document will contain the custom fields for your convenience.\n\n## How to use the external identifier?\n\nYou can just pass along one external identifier attribute when [submitting documents](https://docs.parashift.io/#eb54a4ef-dafa-47b5-b241-199fccbd4c77):\n\n``` json\n{\n    \"data\": {\n        \"type\": \"documents\",\n        \"attributes\": {\n            ...\n            \"external_id\": \"EX12345678910\",\n            ...\n        }\n    }\n}\n\n ```\n\nAny following request to that document will contain the external_id for your convenience.\n\nYou can query for documents with your external identifier.\n\n```\nGET /v2/documents?filter[external_id]=EX12345678910\n\n ```\n\n# Document Processing (Workflow & Status)\n\nEach submitted document is processed asynchronously.\n\nIntegrations usually follow the following pattern.\n\n- You upload a document ([POST submit document](https://docs.parashift.io/#eb54a4ef-dafa-47b5-b241-199fccbd4c77))\n    \n- Parashift processes it\n    \n- (optional) You pull for the status of uploaded documents ([GET list documents](https://docs.parashift.io/#c2a0e890-e03c-41cb-b7ab-a4fed84625e7))\n    \n- You fetch the result ([GET show document](https://docs.parashift.io/#14ef484a-e79e-46ee-b687-08a71d4a4510))\n    \n\nDepending on your use case you want to fetch data at different points in the document process. Therefore it is important to understand the overall document `status` as well as the Parashift processing workflow with `workflow_step` and `workflow_status`.\n\n## Document Status, Workflow Step & Workflow Status\n\nThe top level indicator of the overall document state is `status`. While processing a document the document goes through different `workflow_step`. Each step is devided into different `workflow_status` starting by \"started\" and finalized with \"done\".\n\n### status\n\n| Status | Description |\n| --- | --- |\n| pending | A new document resource has been created and the processing workflow will be started. |\n| in_progress | The document is being processed |\n| done | The document has been processed.  <br>Usually this means that extracted data is present, but please keep in mind that a valid outcome of processing can be that the document was unreadable and no data was extracted.  <br>In this case the document will still have the status _done_ and (if manual validation was involved) _error_codes_ could be set, e.g. `page_missing` or `unreadable` |\n| failed | The document could not (technically) be processed. |\n\n### workflow_step\n\n| Step | Type | Description |\n| --- | --- | --- |\n| inbound | automatic | The document is being received. |\n| inbound_processing | automatic | The document is being processed (enhanced). |\n| separation | automatic | The batch of the document is being separated. |\n| separation_validation | manual | Document is manually (by a human) processed.  <br>If configured and necessary, the batch of a document can be split into more documents. |\n| classification | automatic | The document type of the document is being determined. |\n| classification_validation | manual | Document is manually (by a human) processed.  <br>If configured and necessary, the document type can be confirmed in this step. |\n| extraction | automatic | Data is extracted from the document as per document type configuration. |\n| extraction_validation | manual | Document is manually (by a human) processed.  <br>If configured and necessary, extracted data can be confirmed in this step. |\n| outbound_processing | automatic | The document is being finalised. |\n| done | automatic | No more workflow steps are triggered. |\n| qc | manual,  <br>after _done_ | The document has been selected for quality check purposes. This allows us to continuously improve our service.  <br>This is the only workflow_step that can happen **after** the document reaches _status=done_. |\n\n### workflow_status\n\n| Status | Description |\n| --- | --- |\n| pending | The workflow_step is in the queue and will be started next. |\n| started | The workflow_step has just started. |\n| in_progress | The workflow_step is in progress. |\n| retry | There was a problem or explicit request, the workflow_step has been restarted |\n| failed | The workflow_step had an unrecoverable error, this can lead to the overall `status=failed` |\n| done | The workflow_step has completed successfully. |\n\n# Notifications, Events, Webhooks\n\nIf you want to be notified for status changes, you can configure webhooks to do just that.\n\nA detailed description about webhook capabilities can be found in our support knowledge base:\n\n[More information: Webhooks](https://support.parashift.io/use-webhooks)\n\n# Other\n\n## Compatibility & Changes\n\nBackwards compatible, non-breaking changes can be introduced without prior notice.\n\nThis includes:\n\n- adding new endpoints to the API\n    \n- adding new (optional) parameters to requests\n    \n- extending an API endpoint or object with additional attributes\n    \n- changes to the implementation of this specification (e.g. to improve performance, security, or maintainability \"under the hood\")\n    \n\nTherefor client applications, doing API result parsing, should always be implemented with Forward Compatibility in mind, i.e. not break on receiving additional attributes.\n\n## resource ids and references\n\nThe JSON:API specification mandates that resource ids are strings. Where such ids are included as attributes (independent of whether the referenced resource is included as a relationship), they are also strings, even if they appear to be valid integers.\n\n## Transport Layer Security (TLS)\n\nCommunication with the API uses `https` to protect your data on the transport layer.  \nOnly the following TLS versions and ciphers are supported:\n\n- TLSv1.2\n    \n    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (ecdh_x25519)\n        \n    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (ecdh_x25519)\n        \n    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (ecdh_x25519)\n        \n- TLSv1.3\n    \n    - TLS_AES_256_GCM_SHA384 (ecdh_x25519)\n        \n    - TLS_CHACHA20_POLY1305_SHA256 (ecdh_x25519)\n        \n    - TLS_AES_128_GCM_SHA256 (ecdh_x25519)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"10707090","team":15395,"collectionId":"24903f28-3c81-4a22-a284-8f2c149ef6a0","publishedId":"TzRNDUNy","public":true,"publicUrl":"https://docs.parashift.io","privateUrl":"https://go.postman.co/documentation/10707090-24903f28-3c81-4a22-a284-8f2c149ef6a0","customColor":{"top-bar":"FFFFFF","right-sidebar":"3E515B","highlight":"4DB6CE"},"documentationLayout":"classic-single-column","customisation":null,"version":"8.10.0","publishDate":"2021-05-18T13:36:52.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://parashift.io/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.parashift.io/view/metadata/TzRNDUNy"}