Quickstart

An essential endpoints guide

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

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 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

{
  "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"
    }
  }
}

See the example

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"
}'

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

{
  "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": {}
}

See the example

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='

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.

{
  "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"
    }
  ]
}

See the example

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

Note:

Click here to learn more about collection statuses.

See next:

Last updated

#26: Update: API scopes & Google Sheets Export

Change request updated