Quickstart

An essential endpoints guide

We have prepared a quick tutorial on how to perform basic actions with Alphamoon Workspace including:

• authenticating,

• creating processes,

• uploading files,

• getting the results.

Let's jump straight in!

Authentication

Alphamoon Workspace API uses API keys to authenticate requests. If you want to dig into the API key details, take a look at the following guides:

• Create organization API key (UI)

• Create process API key (UI)

---

• Organization API keys (REST API, beta)

• Process API keys (REST API, beta)

---

• Authenticating

Create process

Let's start by creating a new process and call it "TEST Invoices" using the following endpoint:

Create process

POST /api/v0.3/processes

Request Body

Name	Type	Description
Request body*	String	Value

201: Created Successful response

{
  "id": "f1ed429c666b48bb8b06e21ce17c5d79",
  "name": "TEST Invoices",
  "typeId": "bbe7f45aea884e74bbd011a5f57e87f0",
  "typeName": "Invoices",
  "status": "Ready",
  "version": "0.1",
  "lastUpdated": "2023-06-07T12:09:58Z",
  "usage": null,
  "orgId": "org_Bi1xYf9RLwZV5RUu",
  "createdBy": "google-oauth2|115269842468606867512",
  "createdAt": "2023-06-07T12:09:58Z",
  "updatedAt": "2023-06-07T12:09:58Z",
  "accesses": {
    "google-oauth2|115269842468606867512": {
      "subjectId": "google-oauth2|115269842468606867512",
      "role": "owner",
      "permissions": [
        "workspace.collection:read",
        "workspace.result:read",
        "workspace.process:read",
        "workspace.collection:create",
        "workspace.collection:update",
        "workspace.collection:delete",
        "workspace.file:upload",
        "workspace.file:download",
        "workspace.result:create",
        "workspace.result:update",
        "workspace.result:delete",
        "workspace.process:update",
        "workspace.process:delete",
        "workspace.admin.user:read",
        "workspace.admin.user:invite",
        "workspace.admin.user:manage",
        "workspace.admin.collection:manage"
      ],
      "grantedAt": "2023-06-07T12:09:58Z",
      "grantedBy": "google-oauth2|115269842468606867512"
    }
  }
}

422: Unprocessable Entity Validation Error

See the example

API call

curl -X 'POST' \
  'https://workspace.alphamoon.ai/api/v0.3/processes' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "TEST Invoices",
  "processTypeId": "bbe7f45aea884e74bbd011a5f57e87f0"
}'

Server response

Upload a file

Time to upload a new file to our newly created process. You can do it using Binary or the Base64 endpoints.

Let's do it via Binary one:

Upload file (Binary endpoint)

POST /api/v0.3/processes/{process_id}/files/binary

Upload the file by using the process_id.

Path Parameters

Name	Type	Description
process_id*	String	The id of the process for which you want to upload the file.

Request Body

Name	Type	Description
Request body	String	multipart/form-data

201: Created A new resource was created.

{
  "id": "10372e1d959d42b28d6a1972f0c86888",
  "collectionId": "651158e90ae24560b90116b08cfd8ff5",
  "name": "faktura.pdf",
  "status": "Queued",
  "progress": 0,
  "numberOfPages": null,
  "createdAt": "2023-06-07T12:59:57Z",
  "updatedAt": "2023-06-07T12:59:57Z",
  "metadata": {}
}

422: Unprocessable Entity The server has rejected the request because it cannot process the data as it is.

See the example

API call

curl -X 'POST' \
  'https://beta.workspace.alphamoon.ai/api/v0.3/processes/f1ed429c666b48bb8b06e21ce17c5d79/files/binary' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED ' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@faktura.pdf;type=application/pdf' \
  -F 'checksumMd5=' \
  -F 'collectionId='

Server response

Hint: Want to see how to upload files via Base64? Go to the Upload file tab to learn more.

Get the Results

In order to get the results via API, get the collection_id of the processed file from:

• Upload a file endpoint (Base64 or Binary)

• Get collections endpoint

• The end of the Supervision URL for the corresponding collection e.g. https://workspace.alphamoon.ai/supervision/223742cc9bca43fd81b2d41b0018e4c7

The /results endpoint should be queried every few seconds until the "collectionStatus" has the value "Needs review", "Accepted", "Failed" or "Stopped".

The first two statuses indicate successful processing, enabling the results extraction under the "results" parameter.

Get Collection Results

GET /api/v0.3/results/{collection_id}

Path Parameters

Name	Type	Description
collection-id*	String	The id of the collection for which you want to extract the results.

200: OK Successful Response

{
  "collectionId": "5c8c5791635c44c4b74e08fd5e79163c",
  "collectionName": "Invoice example.pdf",
  "collectionStatus": "Needs Review",
  "processId": "93580f176efb48cda64f25cba74d8ca4",
  "processName": "My invoices",
  "results": [
    {
      "fileId": "b59ef112be5641cdadf9f9e81a13f0d6",
      "fileName": "Invoice example.pdf",
      "status": {
        "status": "Completed",
        "code": "F100",
        "msg": "Completed"
      },
      "documents": [
        {
          "documentId": "1d06f2934b8c47c181b2678153f973f6",
          "name": "Invoice example_0.pdf",
          "classification": {
            "documentClass": "invoice",
            "status": {
              "status": "Completed",
              "code": "C100",
              "msg": "Completed"
            },
            "validation": {
              "status": "No validation",
              "code": "V900",
              "msg": "Validation skipped"
            }
          },
          "extractedData": {
            "account_number": [],
            "bank_name": [],
            "buyer_address": [
              {
                "value": "Przykładowa 1/53 01-887 Warszawa",
                "rawValue": "Przykładowa 1/53 01-887 Warszawa",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "buyer_email": [],
            "buyer_id": [],
            "buyer_name": [
              {
                "value": "Jan Kowalski",
                "rawValue": "Jan Kowalski",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "buyer_phone": [],
            "buyer_vat_number": [],
            "company_number": [],
            "currency": [
              {
                "value": "zł",
                "rawValue": "zł",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Needs Review",
                  "code": "E300",
                  "msg": "Extraction validation failed"
                },
                "validationStatus": {
                  "status": "Needs Review",
                  "code": "V301",
                  "msg": "Confidence validation failed"
                },
                "metadata": {}
              }
            ],
            "iban": [],
            "invoice_date": [
              {
                "value": "2023-06-30",
                "rawValue": "2023-06-30",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "invoice_number": [
              {
                "value": "25247/06/2023",
                "rawValue": "25247/06/2023",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "order_date": [],
            "payment_due_date": [],
            "payment_method": [
              {
                "value": "Przelew/Dotpay",
                "rawValue": "Przelew/Dotpay",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "payment_term": [],
            "purchase_order_number": [],
            "receiver_address": [],
            "receiver_name": [],
            "receiver_nip": [],
            "receiver_phone": [],
            "sell_date": [],
            "seller_address": [
              {
                "value": "Przykładowa 1 03-901 Warszawa",
                "rawValue": "Przykładowa 1 03-901 Warszawa",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "seller_email": [],
            "seller_name": [
              {
                "value": "Furgonetka Spółka z ograniczoną odpowiedzialnością Sp . k",
                "rawValue": "Furgonetka Spółka z ograniczoną odpowiedzialnością Sp . k",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "seller_phone": [],
            "seller_vat_number": [
              {
                "value": "111-222-73-65",
                "rawValue": "111-222-73-65",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "seller_website": [],
            "sort_code": [],
            "swift": [],
            "total_amount": [
              {
                "value": "19,90",
                "rawValue": "19,90",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "total_amount_due": [
              {
                "value": "0,00",
                "rawValue": "0,00",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "total_net_amount": [
              {
                "value": "16,18",
                "rawValue": "16,18",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "total_tax_amount": [
              {
                "value": "3,72",
                "rawValue": "3,72",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Extracted",
                  "code": "E100",
                  "msg": "Extracted"
                },
                "validationStatus": {
                  "status": "Succeeded",
                  "code": "V100",
                  "msg": "Validation succeeded"
                },
                "metadata": {}
              }
            ],
            "delivery_date": [
              {
                "value": "2023-06-30",
                "rawValue": "2023-06-30",
                "converter": {
                  "type": "string",
                  "format": null
                },
                "status": {
                  "status": "Needs Review",
                  "code": "E300",
                  "msg": "Extraction validation failed"
                },
                "validationStatus": {
                  "status": "Needs Review",
                  "code": "V301",
                  "msg": "Confidence validation failed"
                },
                "metadata": {}
              }
            ]
          },
          "extractedTables": {
            "tax_table": [],
            "invoice_items_table": [
              {
                "id": "665ef092b6814862b2043740bfe8922b",
                "rows": [
                  [
                    {
                      "id": "0b1d74cf3f7045f28450d8cb4ee6f99d",
                      "headerLabel": "table_items_position",
                      "text": "1"
                    },
                    {
                      "id": "91e978a1162a412f90214b7f19520bca",
                      "headerLabel": "table_items_description",
                      "text": "Doładowanie konta w serwisie furgonetka.pl na poczet zlecenia zamówienia usług kurierskich"
                    },
                    {
                      "id": "aea1946831294eeab2f40e04e85c92cd",
                      "headerLabel": "table_items_quantity",
                      "text": "1"
                    },
                    {
                      "id": "5d0ef7d7f83c40e991a33aa8ed50cd10",
                      "headerLabel": "table_items_unit",
                      "text": "szt ."
                    },
                    {
                      "id": "349bbc407a6a4677ac19c15c83c29211",
                      "headerLabel": "table_items_net_unit_price",
                      "text": "16,18 zł"
                    },
                    {
                      "id": "c126612b996e4223bedc7f119a419a19",
                      "headerLabel": "table_items_net_amount",
                      "text": "16,18 zł"
                    },
                    {
                      "id": "6a5a40ab25514fb583b0036bd8261741",
                      "headerLabel": "table_items_tax_rate",
                      "text": "23"
                    },
                    {
                      "id": "637cdd64ce3e4656a0c23805194b6ecb",
                      "headerLabel": "table_items_tax_amount",
                      "text": "3,72 zł"
                    },
                    {
                      "id": "b0552a0dfc9e4389ae492924cc28fc5d",
                      "headerLabel": "table_items_amount",
                      "text": "19,90 zł"
                    }
                  ],
                  [
                    {
                      "id": "accffd3079cd419fb409b4bf738f563f",
                      "headerLabel": "table_items_position",
                      "text": ""
                    },
                    {
                      "id": "642b1cfc9fc0404788754d178b158c6d",
                      "headerLabel": "table_items_description",
                      "text": ""
                    },
                    {
                      "id": "5900f5c929674e5aaad8a3609b0db064",
                      "headerLabel": "table_items_quantity",
                      "text": ""
                    },
                    {
                      "id": "e2adc8027c1e4976b3653caa67bb0b05",
                      "headerLabel": "table_items_unit",
                      "text": ""
                    },
                    {
                      "id": "f2e0e6f2b138450eb90c97c5b0a6de0c",
                      "headerLabel": "table_items_net_unit_price",
                      "text": "Razem"
                    },
                    {
                      "id": "b5f9aaa65b574ac7a928b69cf71fbe7e",
                      "headerLabel": "table_items_net_amount",
                      "text": "16,18 zł"
                    },
                    {
                      "id": "3cb1e645c20247b79b69186ad1317929",
                      "headerLabel": "table_items_tax_rate",
                      "text": ""
                    },
                    {
                      "id": "99aa9f1f69334f6199463bc35f623706",
                      "headerLabel": "table_items_tax_amount",
                      "text": "3,72 zł"
                    },
                    {
                      "id": "1ef9821997ad4c3b929e68ca3fad6b3a",
                      "headerLabel": "table_items_amount",
                      "text": "19,90 zł"
                    }
                  ]
                ]
              }
            ]
          },
          "missingExtractions": [
            "buyer_vat_number"
          ],
          "status": {
            "status": "Completed",
            "code": "100",
            "msg": "Completed"
          }
        }
      ],
      "totalPages": 1,
      "createdAt": "2023-07-13T12:16:33Z"
    }
  ]
}

422: Unprocessable Entity Validation Error

See the example

API call

curl -X 'GET' \
  'https://workspace.alphamoon.ai/api/v0.3/results/f7c9e9d77b9e4c3c80bb1f3beaa1a2b3' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic API_KEY_BASE64_ENCODED'

Server response

Note:

Click here to learn more about collection statuses.

See next: