Learn how you can use the API to write programs that submit data to your projects or download the generated documents from your projects.
MergeOS includes an Application Programming Interface (API) that allows software developers to interact with parts of the system via code.
API Resources
You need to create an API key before you can call any of the API endpoints.
Creating an API Key
Click on your name in the main left menu from any page. You'll be taken to the Account Details page.
Click on the API Settings tab.
Click on the Add API Key button. A dialog box will display where you can name the key.
Name the API Key
Enter a name for the API Key and click the Add Key button.
The API key will display after you create it
Copy the API Key and store it somewhere safe. It will only display this once, and you can't retrieve it again.
If you need to invalidate the key, you can delete it using the trash icon.
Other Resources
All the API end-points work on different resources within your account. Each resource has a unique key that you will need to use in the URL of the API call. You can access these unique keys from the API Settings page.
Unique API Resource Keys
Your Organisation Key is required for every API call.
Each Project is listed, showing the Project Key and the Data Table Key attached to that project.
Authentication
You can authenticate to the API by using your API key in the HTTP authorization bearer token header. A slightly lower security approach is to provide your API key with the api_key query parameter.
All API requests must be authenticated and made over HTTPS.
Examples
# USING A BEARER TOKEN
$ curl https://www.mergeos.com/api/v1/YOUR_ORGANISATION_KEY/me \-H "Authorization: Bearer YOUR_API_KEY"
# USING A QUERY PARAMETER
$ curl https://www.mergeos.com/api/v1/YOUR_ORGANISATION_KEY/me?api_key=YOUR_API_KEY
The above endpoint just returns your organisation and personal details. Use it to test that your connection is working.
This section explains and demonstrates the endpoints available in the API. Please note that all data shown is sample data only. Some keys in the data table JSON objects are dependant on the fields in your actual data tables.
The following examples show data from the Example - Client Letter 1 project which is automatically created in your account on signup. The KEYS will different in your account, but the column names and data will be the same.
Datatables
The following end-points are for working with the Data Tables in your account.
List Data Tables
To list all the Data Tables within your account, issue a GET request to your Organisations datatables endpoint.
// EXAMPLE RESPONSE
{
"key": "tbl9KIj2WCw4udv0d",
"display_name": "Example - Clients",
"description": "An example data table with clients",
"created_date_utc": "2020-04-17T06:00:33.000000Z",
"updated_date_utc": "2020-04-17T06:00:33.000000Z",
"columns": [
{
"key": "fldtk4bQLsE8ReVxZ",
"name": "Client Id",
"dataType": "number"
},
...
]
}
The columns array will contain the columns you have configured in your data table.
List Data Table Records
To get the records within a data table, issue a GET request to the datarecords endpoint with the KEY of the data table.
QUERY PARAMETERS The following query parameters can be used on this endpoint
includeJobs Boolean. True by default. Return the Job array which includes includes information about the projects that have processed this data record, including the data table and generated documents.
// EXAMPLE RESPONSE
[
{
"key": "rcdQ8ehfkUOdUxyVE",
"fields": {
"Client ID": 1,
"First Name": "Missy",
"Last Name": "Coucher",
"Email Address": "missy@example.com",
"Client Since": "10/01/2003"
},
"created_at": "2020-04-05T02:48:51.000000Z",
"jobs": [
{
"key": "jobl196GeUQV5elaC",
"process_status": "PROCESSED",
"project": {
"key": "prj2HIOmnXwdjN9ws",
"display_name": "Example - Client Letter 1",
"description": "This example project creates a custom letter for each client in the main data table. It uses a related data table to create a chart showing the change in their finances over two quarters.",
"run_status": 1,
"is_preprocess_enabled": true,
"project_document_templates": [
{
"is_enabled": true,
"is_save_enabled": true,
"is_pdf_enabled": true,
"is_word_enabled": true,
"document_template": {
"key": "fler1TE5Sy0GbEvjD",
"file_name": "example quarterly client letter.docx",
"description": "This is an example document template that creates a client quarterly letter. It shows how variables are inserted into a word document and includes charts, a table and calculated values from a spreadsheet.",
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"file_size": 2001284,
"created_at": "2020-04-05T02:48:51.000000Z"
},
"created_at": "2020-04-05T02:48:51.000000Z"
}
],
"datatable": {
"key": "tbl9KIj2WCw4udv0d",
"display_name": "Example - Clients",
"description": "An example data table with clients",
"created_date_utc": "2020-04-05T02:48:51.000000Z",
"updated_date_utc": "2020-04-05T02:48:51.000000Z",
"columns": [
{
"key": "fldtk4bQLsE8ReVxZ",
"name": "Client ID",
"dataType": "number"
},
{
"key": "fldR9p3yfmDZpbTaa",
"name": "First Name",
"dataType": "text"
},
{
"key": "fld8w38henDLHUZJo",
"name": "Last Name",
"dataType": "text"
},
{
"key": "fldbHSU1S2JdJzTkw",
"name": "Email Address",
"dataType": "email"
},
{
"key": "fldXWDpkADxGeXGg7",
"name": "Client Since",
"dataType": "date"
}
]
},
"created_at": "2020-04-05T02:48:51.000000Z"
},
"generated_documents": [
{
"key": "fleDX10XwjEmrvG4T",
"file_extension": "xlsx",
"file_name": "Missy Coucher Preprocess.xlsx",
"file_size": 22820,
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"created_at": "2020-04-27T23:11:08.000000Z",
"url": "https://www.mergeos.com/api/v1/orgxQLcXdnE4jp5op/files/generated_documents/fleDX10XwjEmrvG4T"
},
{
"key": "fle58Zu5itVhDrhTp",
"file_extension": "docx",
"file_name": "Missy Coucher Client Letter.docx",
"file_size": 1574156,
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"created_at": "2020-04-27T23:11:13.000000Z",
"url": "https://www.mergeos.com/api/v1/orgxQLcXdnE4jp5op/files/generated_documents/fle58Zu5itVhDrhTp"
},
{
"key": "flebkxqjeNOFeVpqA",
"file_extension": "pdf",
"file_name": "Missy Coucher Client Letter.pdf",
"file_size": 887025,
"mime_type": "application/pdf",
"created_at": "2020-04-27T23:11:15.000000Z",
"url": "https://www.mergeos.com/api/v1/orgxQLcXdnE4jp5op/files/generated_documents/flebkxqjeNOFeVpqA"
}
],
"created_at": "2020-04-27T23:11:02.000000Z"
}
]
},
....
]
Get a single Data Table Record
To get one record from a data table, issue a GET request to the datarecords endpoint with the KEY of the data table and the KEY of the data record.
QUERY PARAMETERS The following query parameters can be used on this endpoint.
includeJobs Boolean. True by default. Return the Job array which includes includes information about the projects that have processed this data record, including the data table and generated documents.
// EXAMPLE RESPONSE - See all the fields of a data record in the example above: List Data Table Records
{
"key": "rcdQ8ehfkUOdUxyVE",
"fields": {
"Client ID": 1,
"First Name": "Missy",
"Last Name": "Coucher",
"Email Address": "missy@example.com",
"Client Since": "10/01/2003"
},
"created_at": "2020-04-05T02:48:51.000000Z",
"jobs": [
...
]
}
Create a Data Table Record
To create a new record in a data table, issue a POST request to the datarecords endpoint with the KEY of the data table.
The body of your request should contain a single JSON object with one key fields, which contains the field names and values of the record to insert. You can also include an array of these objects to insert multiple rows at once.
# EXAMPLE REQUEST - Single Insert
$ curl -v -X POST "https://www.mergeos.com/api/v1/YOUR_ORGANISATION_KEY/datatables/DATATABLE_KEY" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"fields": {
"Client ID": 5,
"First Name": "Postman Test First Name",
"Last Name": "Postman Test Last Name",
"Email Address": "Postman@example.com",
"Client Since": "01/05/2020"
}
}'
// Example Response
{
"key": "rcdO9VmjOB7KyJ7Y1",
"fields": {
"Client ID": 5,
"First Name": "Postman Test First Name",
"Last Name": "Postman Test Last Name",
"Email Address": "Postman@example.com",
"Client Since": "01/05/2020"
},
"created_at": "2020-05-01T04:58:24.000000Z",
"jobs": []
}
List Projects
To list all the Projects within your account, issue a GET request to your Organisations projects endpoint.
// EXAMPLE RESPONSE - See all the fields of a data record in the example above: List Data Table Records
[
{
"key": "prjeffthyuFP75OAu",
"display_name": "Home Page Example - 1",
"description": "This example project used on the home page example section.",
"run_status": 1,
"is_preprocess_enabled": true,
"project_document_templates": [
{
"is_enabled": true,
"is_save_enabled": true,
"is_pdf_enabled": true,
"is_word_enabled": true,
"document_template": {
"key": "flewIjIuhcL6ZA0f5",
"file_name": "example quarterly client letter.docx",
"description": "This is an example document template that creates a client quarterly letter. It shows how variables are inserted into a word document and includes charts, a table and calculated values from a spreadsheet.",
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"file_size": 2004042,
"created_at": "2020-04-17T06:00:35.000000Z"
},
"created_at": "2020-04-17T06:00:35.000000Z"
}
],
"datatable": {
"key": "tblKjjvVKo4fitrvX",
"display_name": "Example 1 - Prospects",
"description": "An example data table with clients",
"created_date_utc": "2020-04-17T06:00:31.000000Z",
"updated_date_utc": "2020-04-22T21:51:56.000000Z",
"columns": [
{
"key": "flduMqwwpa0CoX4uu",
"name": "Client ID",
"dataType": "number"
},
...
]
},
"created_at": "2020-04-17T06:00:33.000000Z"
},
...
]
Get a single Project
To get a single project, issue a GET request to the projects endpoint with the KEY of the project
// EXAMPLE RESPONSE
{
"key": "prjeffthyuFP75OAu",
"display_name": "Home Page Example - 1",
"description": "This example project used on the home page example section.",
"run_status": 1,
"is_preprocess_enabled": true,
"project_document_templates": [
...
],
"datatable": { },
"created_at": "2020-04-17T06:00:33.000000Z"
}
Get a single Project Job
To get a single project job, issue a GET request to the projects endpoint with the KEY of the project.
A project job describes the processing of a single record. It is only created for a running project. It contains information about the documents that have been generated for the record.
You can get the JOB_KEY from the result when creating a new data record, or when querying a data table record.
