cURL
This page contains various examples of using the CargoX API with cURL commands for common operations.
Fetching Contacts
This example shows how company contacts can be fetched using bearer token for request authorization.
curl --location --request GET 'https://cargox.digital/api/v3/companies/self/contacts/list/' \
--header 'Authorization: Bearer acaYpzlT7OL6gw1yI9W1ovtTZtFmQa'
If the bearer token is valid, the above cURL command returns the following JSON response:
[
{
"company_id": "aa69e1b4-a6ef-4a64-aa17-6c3f7adf8662",
"company": {
"name": "Inviter company",
"branch": null,
"address": "Sample street 123",
"address2": "",
"postal_code": "1234",
"city": "Ljubljana",
"country": "SI",
"country_name": "Slovenia",
"website": "https://cargox.io",
"vat_number": null,
"logo": null,
"logo_name": "",
"id": "aa69e1b4-a6ef-4a64-aa17-6c3f7adf8662"
},
"my_inbox_id": "96bf8b27-65fb-4c46-9f10-067441916eaa",
"their_inbox_id": "dd41e532-f1a2-4662-bd4a-bd16c96e8a17",
"their_inbox": {
"company_id": "d38ae6ce-1f33-4ed0-9f25-6b6c8f860680",
"company": {
"name": "Contact company",
"branch": null,
"address": "Sample boulevard 55",
"address2": "",
"postal_code": "98767",
"city": "Bern",
"country": "CH",
"country_name": "Switzerland",
"website": null,
"vat_number": null,
"logo": null,
"logo_name": "",
"id": "d38ae6ce-1f33-4ed0-9f25-6b6c8f860680"
},
"name": "Default",
"ethereum_address": "0x29B4E3715E9926D50eAbDfAE3619d097128926C5",
"id": "dd41e532-f1a2-4662-bd4a-bd16c96e8a17"
},
"email": null,
"message": null,
"note": null,
"invitation_code": null,
"status": "accepted",
"created": "2020-05-27T09:13:38.521230Z",
"created_by_id": "0102f020-6307-4a60-b7bb-c8a7dbea4d9d",
"created_by": {
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"telephone": null,
"company_id": "aa69e1b4-a6ef-4a64-aa17-6c3f7adf8662",
"company": { "..." },
"logo": null,
"logo_name": "",
"id": "0102f020-6307-4a60-b7bb-c8a7dbea4d9d"
},
"resolved": "2020-05-27T09:13:38.289849Z",
"resolved_by_id": "a0f9e92b-54c2-45ce-aa61-97e2ae757549",
"resolved_by": { "..." },
"contact_person": { "..." },
"id": "fe01f72e-8599-4081-bcec-ed5b9301d039"
}
]
If bearer token is invalid or expired, the following 403 Forbidden response is returned:
{
"detail": "Authentication credentials were not provided."
}
Listing Envelopes
This example shows how company envelopes can be listed using bearer token for request authorization.
curl --location --request GET 'https://localhost:8081/api/v3/companies/by-id/aa69e1b4-a6ef-4a64-aa17-6c3f7adf8662/inboxes/by-id/4ebccdea-de80-42b6-b99e-2c821a121251/envelopes/list/' \
--header 'Authorization: Bearer acaYpzlT7OL6gw1yI9W1ovtTZtFmQa'
If the bearer token is valid, the above cURL command returns a list of all Envelope objects that belong to this company, in JSON format. Below is an example of such a response (truncated for brevity):
[
{
"id": "b84acbfe-c55d-4f1f-bdd2-b121fa8f603c",
"owner_id": "4ebccdea-de80-42b6-b99e-2c821a121251",
"recipient_id": null,
"message": "",
"type": "outgoing",
"created": "2020-08-03T07:30:01.328929Z",
"sent": null,
"archived": null,
"delivered": null,
"action_performed_by_id": null,
"sealed": false,
"can_be_sealed": false,
"is_draft": true,
"sender_inbox_id": null,
"sender": null,
"delivered_envelope_opened": false,
"delivery_status": null,
"can_be_archived": false,
"can_be_unarchived": false,
"read_by_user": false,
"attachments": [
{
"id": "8a4c7ffb-774a-4025-be26-9f59efef42a9",
"envelope_id": "b84acbfe-c55d-4f1f-bdd2-b121fa8f603c",
"document_token_id": "e24b6aa0-0414-434a-a730-64d7b17f3c1b",
"document_token": {
"id": "e24b6aa0-0414-434a-a730-64d7b17f3c1b",
"storage_type": "disk",
"watermark_generated": true,
"document_id": "9ebf2756-bc8b-454b-8fa7-e997b45e1a35",
"document": {
"id": "9ebf2756-bc8b-454b-8fa7-e997b45e1a35",
"current_owner_id": "4ebccdea-de80-42b6-b99e-2c821a121251",
"uploaded_by_id": "be6c5b4e-3d36-4a1f-9a8b-69a215518ccb",
"uploaded_by": { "..." },
"type": {
"id": "GOO",
"name": "Guarantee of origin",
"short_name": "GOO",
"color": 20,
"categories": ["Energy"],
"is_smart_bl": false,
"blockchain_support": "full"
},
"document_id": null,
"display_name": "000671_2124311_potrdiloAo_30_07_2018_21_38_40_KXXOkj9_kYPMb8g (1).pdf",
"file_name": "000671_2124311_potrdiloAo_30_07_2018_21_38_40_KXXOkj9_kYPMb8g (1).pdf",
"file_size": 244950,
"file_content_type": "application/pdf",
"icon": "pdf",
"file_type": "PDF",
"created": "2020-08-03T07:30:03.099566Z"
},
"attachment_count": 1,
"is_on_blockchain": false,
"can_be_destroyed": false,
"can_be_accomplished": false,
"created": "2020-08-03T07:30:03.542241Z"
},
"used_in_envelope_id": null,
"can_be_forwarded": false
}
],
"delivered_envelope_id": null,
"document_token_transactions": [],
"pay_to_collect": false,
"pay_to_collect_response": 0
}
]
If bearer token is invalid or expired, the following 403 Forbidden response is returned:
{
"detail": "Authentication credentials were not provided."
}
Inviting Companies to the Platform
This example shows how to send contact invitations to companies. If the invited company accepts this invitation, both companies become connected and can start exchanging documents with each other. The following example is a cURL request using bearer token for request authorization.
curl --location --request POST 'https://cargox.digital/api/v3/companies/self/contacts/' \
--header 'Authorization: Bearer acaYpzlT7OL6gw1yI9W1ovtTZtFmQa' \
--header 'Content-Type: application/json' \
--data-raw '[{"email": "[email protected]", "message": "Personalized message."},
{"email": "[email protected]"},
{"email": "[email protected]"}]'
Request body is a list of objects in JSON format. Each object must have an email property and can have an optional message property. If the bearer token is valid, an invitation email is sent to the email address with the optional personalized message. The above cURL request returns the following JSON response:
{
"successful_invites": [
{
"company_id": "aa69e1b4-a6ef-4a64-aa17-6c3f7adf8662",
"company": {
"name": "Inviter company",
"branch": null,
"address": "Sample street 123",
"address2": "",
"postal_code": "1234",
"city": "Ljubljana",
"country": "SI",
"country_name": "Slovenia",
"website": "https://cargox.io",
"vat_number": null,
"logo": null,
"logo_name": "",
"id": "aa69e1b4-a6ef-4a64-aa17-6c3f7adf8662"
},
"my_inbox_id": "96bf8b27-65fb-4c46-9f10-067441916eaa",
"their_inbox_id": null,
"their_inbox": null,
"email": "[email protected]",
"message": "Personalized message.",
"note": null,
"invitation_code": null,
"status": "pending",
"created": "2020-07-27T13:16:26.981797Z",
"created_by_id": "55ba1326-e07f-4293-b3b3-84db9f6efb90",
"created_by": { "..." },
"resolved": null,
"resolved_by_id": null,
"resolved_by": null,
"contact_person": null,
"id": "e59c2621-bba4-4b40-b503-f8a88674f8ee"
}
],
"failed_invites": [
{
"email": "[email protected]",
"message": "",
"error": "Company is already invited."
},
{
"email": "[email protected]",
"message": "",
"error": "The domain domain-does-not-exist.com could not be found."
}
]
}
Response consists of two lists named successful_invites and failed_invites. The first is a list of serialized Contact objects that were created as a result of successfully sent invitations. The latter is a list of invitation objects that could not be successfully processed. Reason for failure is listed under the error property in each object.
If bearer token is invalid or expired, the following 403 Forbidden response is returned:
{
"detail": "Authentication credentials were not provided."
}
Uploading Documents to New Draft
This example shows how to upload documents to a new draft. The following example is a cURL POST request using bearer token for request authorization. A new draft is created as a result of this request.
curl --location --request POST 'https://cargox.digital/api/v3/companies/self/inboxes/by-id/86252a14-71b8-4309-8d99-b3f06400385f/envelopes/' \
--header 'Authorization: Bearer qB3b6Jqb8iyTP7bLhJ7wnRqTpf2Yaa' \
--form 'documents=@/path/to/document.pdf' \
--form 'documents=@/path/to/another-document.pdf'
Request body is a FormData object. Besides the documents property, other draft fields can be set with the same request (see API reference). On success, the above cURL request returns a JSON response with the created Envelope object (truncated for brevity):
{
"id": "e4d9c249-2f30-481f-b436-1951b4de3b80",
"owner_id": "86252a14-71b8-4309-8d99-b3f06400385f",
"recipient_id": null,
"message": null,
"type": "outgoing",
"created": "2020-07-27T14:26:00.456069Z",
"sent": null,
"sealed": false,
"can_be_sealed": false,
"is_draft": true,
"attachments": [
{
"id": "4ff8bba6-ed8c-48e6-b004-c7a19481838d",
"envelope_id": "87395226-535d-4b6b-b7fa-c11bcf9719a6",
"document_token_id": "dd442f79-93fa-426b-a552-4c9e25f9db33",
"document_token": {
"id": "dd442f79-93fa-426b-a552-4c9e25f9db33",
"document_id": "e49b6639-bbbc-48d1-867b-047bcd5664ca",
"document": {
"id": "e49b6639-bbbc-48d1-867b-047bcd5664ca",
"display_name": "document.pdf",
"file_name": "document.pdf",
"file_size": 2830,
"file_content_type": "application/pdf",
"created": "2020-07-27T14:26:01.700658Z"
}
}
},
{
"id": "e43480cb-400c-430a-9420-38ddef4ae011",
"document_token": {
"document": {
"display_name": "another-document.pdf",
"file_name": "another-document.pdf",
"file_size": 147786,
"created": "2020-07-27T14:29:33.199650Z"
}
}
}
],
"pay_to_collect": false
}
Response is a serialized Envelope object in JSON format representing the newly created draft. Uploaded documents can be found in the attachments list.
If bearer token is invalid or expired, the following 403 Forbidden response is returned:
{
"detail": "Authentication credentials were not provided."
}
Uploading Documents to Existing Draft
This example shows how to upload documents to an existing draft. The following example is a cURL PATCH request using bearer token for request authorization.
curl --location --request PATCH 'https://cargox.digital/api/v3/companies/self/inboxes/by-id/86252a14-71b8-4309-8d99-b3f06400385f/envelopes/by-id/87395226-535d-4b6b-b7fa-c11bcf9719a6/' \
--header 'Authorization: Bearer qB3b6Jqb8iyTP7bLhJ7wnRqTpf2Yaa' \
--form 'documents=@/path/to/document.pdf' \
--form 'documents=@/path/to/another-document.pdf'
Request body is a FormData object. Besides the documents property, other draft fields can be patched with the same request (see API reference). On success, the above cURL request returns a JSON response with the patched Envelope object (structure similar to the previous example).
Response is a serialized Envelope object in JSON format representing the patched draft. Uploaded documents can be found in the attachments list.
If bearer token is invalid or expired, the following 403 Forbidden response is returned:
{
"detail": "Authentication credentials were not provided."
}
Seal a Draft and Transfer an Envelope
This example shows how to seal a draft and complete the entire transfer workflow.
Create a Draft
The following example is a cURL POST request using bearer token for request authorization. A new draft is created as a result of this request.
curl --location --request POST 'https://cargox.digital/api/v3/companies/self/inboxes/by-id/{{YOUR_INBOX_ID_HERE}}/envelopes/' \
--header 'Authorization: Bearer qB3b6Jqb8iyTP7bLhJ7wnRqTpf2Yaa' \
--data-raw '{"recipient_id": "{{RECIPIENT_ID_HERE}}","message": "This is a message","pay_to_collect":false}'
Request body is a FormData object. Besides the documents property, other draft fields can be set with the same request (see API reference). On success, the above cURL request returns a JSON response. Please mind the id attribute. You will need it later.
{
"id": "086e2234-a718-43ae-9076-ee7583b84437",
"owner_id": "c16d67b9-a9a2-4332-8301-a671bb75c199",
"recipient_id": "04906b82-beb1-42ea-8aac-1ca8afdcdb05",
"message": "This is a message",
"type": "outgoing",
"specialization_type": "standard",
"created": "2021-04-16T12:13:53.726772Z",
"sent": null,
"archived": null,
"delivered": null,
"action_performed_by_id": null,
"action_performed_by": null,
"action_performed_by_company_id": null,
"action_performed_by_company": null,
"sealed": false,
"can_be_sealed": false,
"is_draft": true,
"sender_inbox_id": null,
"sender": null,
"delivered_envelope_opened": false,
"delivery_status": null,
"can_be_archived": false,
"can_be_unarchived": false,
"read_by_user": false,
"attachments": [],
"delivered_envelope_id": null,
"failed_delivery_envelope_id": null,
"failed_outgoing_id": null,
"document_token_transactions": [],
"pay_to_collect": false,
"pay_to_collect_response": 0,
"meta_data": {},
"credits_spent_amount": null,
"is_first_acid_filing": false
}
Add Documents to Draft
To add documents to the draft please refer to the documentation on uploading documents to existing draft.
Seal the Draft
When documents are attached to a draft we can seal it.
curl --location --request POST 'https://cargox.digital/api/v3/companies/self/inboxes/by-id/{{YOUR_INBOX_ID_HERE}}/envelopes/by-id/{{YOUR_ENVELOPE_ID_HERE}}' \
--header 'Authorization: Bearer qB3b6Jqb8iyTP7bLhJ7wnRqTpf2Yaa' \
--data-raw '{"sealed":true}'
Fetch the Transactions
In order to transfer the envelope we need to fetch the transactions, sign them with the appropriate blockchain key and send them back to the envelope.
To get the transactions use the following call - make sure you enter the appropriate ethereum_address (this is the public address of the blockchain key that will be used to sign the transfers):
curl --location --request POST 'https://cargox.digital/api/v3/companies/self/inboxes/by-id/{{YOUR_INBOX_ID_HERE}}/envelopes/by-id/{{YOUR_ENVELOPE_ID_HERE}}/workflow/' \
--header 'Authorization: Bearer qB3b6Jqb8iyTP7bLhJ7wnRqTpf2Yaa' \
--data-raw '{"action":"generate_issue_hash","ethereum_address":"{{YOUR_BLOCKCHAIN_KEY_PUBLIC_ADDRESS}}"}'
The result is a JSON document with the transaction details (one for each document in the draft - there are two in this example):
[
{
"document_token_id": "75c6e24c-1639-4ffa-9741-2662c85e9ac5",
"relayed_transaction": {
"hash": "0x63a4e9ba2f2b0d3bb9b9ccdd81940255da098871efc7ad6c0bffa38fb777b2fd",
"relay_nonce": 1,
"recipient": "0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851",
"relayed_for": "0x3154F1709accF77147DF12C7AE07B307269388ef",
"transaction_data": "0x3266df5b00000000000000000000000088989054fde4c610c42a20cdc256ba6d8276f7a20000000000000000000000000000000075c6e24c16394ffa97412662c85e9ac5656c97fb4af2522b4459effe1e7b424b824397a19b77cc9ce1a8ff5b1970f7b000000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000020000000000000000000000000795e6c852b579e8fb396b9d0e441d63d30fd338b0000000000000000000000000000000000000000000000000000000000000001"
}
},
{
"document_token_id": "b8dd76af-2dac-461a-b75c-030575d52bad",
"relayed_transaction": {
"hash": "0xe5e4394c74d55c1e9cc3096be9bb1a01f3881e6dd4b6a879324bc8ed16b76f00",
"relay_nonce": 2,
"recipient": "0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851",
"relayed_for": "0x3154F1709accF77147DF12C7AE07B307269388ef",
"transaction_data": "0x3266df5b00000000000000000000000088989054fde4c610c42a20cdc256ba6d8276f7a200000000000000000000000000000000b8dd76af2dac461ab75c030575d52bad168237474b53735eec9f9522ef080aca1100e08f320f38e12e21863fbdc3816300000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000020000000000000000000000000cf06ec4f5f4d8c4fedd2f5484448ef0e5709520b0000000000000000000000000000000000000000000000000000000000000001"
}
}
]
Sign the Transactions
Make sure to cryptographically sign the hash of the transaction and not the transaction_data.
Here is a JavaScript example of doing so:
web3.eth.personal.sign(
response[0]['relayed_transaction']['hash'],
accounts[0],
function (e, signature) { ... }
)
Please refer to the Signing page for examples in JavaScript, PHP, Go, and C#.
Send the Signed Transactions
Send back the signed transactions:
curl --location --request POST 'https://cargox.digital/api/v3/companies/self/inboxes/by-id/{{YOUR_INBOX_ID_HERE}}/envelopes/by-id/{{YOUR_ENVELOPE_ID_HERE}}/workflow/' \
--header 'Authorization: Bearer qB3b6Jqb8iyTP7bLhJ7wnRqTpf2Yaa' \
--data-raw '{"action":"issue","data":[{"relayed_transaction":{"hash":"0x63a4e9ba2f2b0d3bb9b9ccdd81940255da098871efc7ad6c0bffa38fb777b2fd","relay_nonce":1,"recipient":"0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851","relayed_for":"0x3154F1709accF77147DF12C7AE07B307269388ef","transaction_data":"0x3266df5b00000000000000000000000088989054fde4c610c42a20cdc256ba6d8276f7a20000000000000000000000000000000075c6e24c16394ffa97412662c85e9ac5656c97fb4af2522b4459effe1e7b424b824397a19b77cc9ce1a8ff5b1970f7b000000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000020000000000000000000000000795e6c852b579e8fb396b9d0e441d63d30fd338b0000000000000000000000000000000000000000000000000000000000000001","signature":"0x4facda7cdac8f808466765674fa9b4d23d7dde9bce63d064593a737ec2c210bd589edf786a3c6ea9a7233da985e4b7d822275ad625e085f51e9df925a7b38cb01c"},"document_token_id":"75c6e24c-1639-4ffa-9741-2662c85e9ac5"},{"relayed_transaction":{"hash":"0xe5e4394c74d55c1e9cc3096be9bb1a01f3881e6dd4b6a879324bc8ed16b76f00","relay_nonce":2,"recipient":"0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851","relayed_for":"0x3154F1709accF77147DF12C7AE07B307269388ef","transaction_data":"0x3266df5b00000000000000000000000088989054fde4c610c42a20cdc256ba6d8276f7a200000000000000000000000000000000b8dd76af2dac461ab75c030575d52bad168237474b53735eec9f9522ef080aca1100e08f320f38e12e21863fbdc3816300000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000020000000000000000000000000cf06ec4f5f4d8c4fedd2f5484448ef0e5709520b0000000000000000000000000000000000000000000000000000000000000001","signature":"0x5ed416cc48673d0ed3e7fd1bf1a18f183992d5164a73762cd43f73a88e13480a5a7e211c"},"document_token_id":"b8dd76af-2dac-461a-b75c-030575d52bad"}]}'
Here is the data payload formatted for easier inspection:
[
{
"relayed_transaction": {
"hash": "0x63a4e9ba2f2b0d3bb9b9ccdd81940255da098871efc7ad6c0bffa38fb777b2fd",
"relay_nonce": 1,
"recipient": "0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851",
"relayed_for": "0x3154F1709accF77147DF12C7AE07B307269388ef",
"transaction_data": "0x3266df5b00000000000000000000000088989054fde4c610c42a20cdc256ba6d8276f7a20000000000000000000000000000000075c6e24c16394ffa97412662c85e9ac5656c97fb4af2522b4459effe1e7b424b824397a19b77cc9ce1a8ff5b1970f7b000000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000020000000000000000000000000795e6c852b579e8fb396b9d0e441d63d30fd338b0000000000000000000000000000000000000000000000000000000000000001",
"signature": "0x4facda7cdac8f808466765674fa9b4d23d7dde9bce63d064593a737ec2c210bd589edf786a3c6ea9a7233da985e4b7d822275ad625e085f51e9df925a7b38cb01c"
},
"document_token_id": "75c6e24c-1639-4ffa-9741-2662c85e9ac5"
},
{
"relayed_transaction": {
"hash": "0xe5e4394c74d55c1e9cc3096be9bb1a01f3881e6dd4b6a879324bc8ed16b76f00",
"relay_nonce": 2,
"recipient": "0xc8e04f362dB54e3FFeE14fC173f231B1A09DE851",
"relayed_for": "0x3154F1709accF77147DF12C7AE07B307269388ef",
"transaction_data": "0x3266df5b00000000000000000000000088989054fde4c610c42a20cdc256ba6d8276f7a200000000000000000000000000000000b8dd76af2dac461ab75c030575d52bad168237474b53735eec9f9522ef080aca1100e08f320f38e12e21863fbdc3816300000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000020000000000000000000000000cf06ec4f5f4d8c4fedd2f5484448ef0e5709520b0000000000000000000000000000000000000000000000000000000000000001",
"signature": "0x5ed416cc48673d0ed3e7b5cecc30563c4b0ff9dce4915ce96c9b87426787de5245d55a065512e7fd1bf1a18f183992d5164a73762cd43f73a88e13480a5a7e211c"
},
"document_token_id": "b8dd76af-2dac-461a-b75c-030575d52bad"
}
]
It is the response of the previous call but with each of the relayed_transaction objects annotated with a signature.
This call instructs the backend to issue the transaction on the blockchain.