NAV Navbar
Logo
javascript

INTRODUCTION

Welcome to the Juro API!

Juro is a platform for automating legal contract workflows, integrating contracts with data sources and managing contract lifecycles.

The Juro API allows you to integrate, generate, and e-sign contracts, be notified of contract activity and query your existing contract stack for structured data about the contract itself and any associated metadata. Gain insight into your contract pipeline, obligations and terms in a machine readable form.

We have setup webhooks so that you can have an easy way of subscribing to events happening on your account, with your contracts.

TUTORIAL

Templates and contracts

A contract in Juro usually is built on top of a generic template. You can create unlimited number of contracts based on a template with infinite variations to either the text of the contract or it’s input data.

Contract templates in Juro consist of two main elements, body and smart fields:

(1) Main body

The main body is where most of the legal language is typically incorporated in templates and this part doesn’t change with each instance of a contract created from that template.

(2) Smart fields

Smart fields are dynamic elements in a template, which can either be integrated with data sources (smart field replacements) or linked to a Q&A and help texts in our user interface.

Smart fields can be populated by either the contract owner and/or the counterparty. Populating smart fields is done through the contract create method sending fields property or the counterparty answering questions in a Q&A flow immediately prior to signing.

In the latter case, before signing, the counterparty will be prompted to answer a few questions when the signing link is clicked, which will populate smart fields or potentially affect smart field replacements.

Signatures

The counterparty signature should be acquired by the counterparty following a Juro signing link reading the terms and signing the contract in accordance with Juro’s electronic signing tool. This will verify the identity of the signatory and deliver an immutable audit trail.

Electronic signature for the owner side should be sent in base64 format. It should be image/png encoded in base64 format with the dimensions (475x175 pixels).

Contract lifecycle

The first phase of the lifecycle of your contract starts when you first create a draft contract instance from a template and ends in the fully_signed status, at which point all participants have signed the contract and it becomes legally binding and immutable.

After all signatures are saved and updated on your contract, the contract will automatically be moved to fully signed status. That will indicate that you can now access a pdf of the contract signed by all parties (which is emailed to both parties by default) and the contract and its audit trail becomes immutable.

If you get any comments on the contract in question from your counterparties, the contract owner will be notified via email (or Slack if integrated) and will need to reply to comments via Juro’s UI.

The second phase of your contract (post signing) incorporates key obligation milestones, execution of particular contract terms and culminates in a renewal of that contract. Coming soon to the Juro API…

Getting started

To process your first contract you will need to follow these steps:

  1. Get your API Key;
  2. Get the id of your template to use for the contract generation (e.g. sample NDA template);
  3. Pass all the necessary information for the contract to be created;
  4. After you have generated the contract you can now send it for signing as well as sign yourself;
  5. When the contract is signed you will be able to download the pdf of the fully signed contract.

Responding to events

A lot of integration cases revolve around syncing information between multiple systems (for example, pulling data out of an opportunity in Salesforce) and triggering events (for example uploading a pdf of fully signed contract to an opportunity in Salesforce).

You can use webhooks to subscribe to events and then decide what you want to do when that event happens. The following is a list of events currently supported by Juro.

AUTHENTICATION

Getting an authentication token

In order to get your token please go to your account settings or contact us.

You can register for an account here.

Authenticating your API calls

Make sure to replace <API_KEY> with your API key.

You have multiple ways of authenticating with Juro API. The simplest way is to use an API key provided to you when you have created an account within Juro. Another way is to use a two factor authentication (here’s more on that).

Please don’t forget to include the API key in all of your requests. You can easily do that by adding x-api-key to your headers.

x-api-key: YourAPIKey

HEALTH

Check Juro health

Request

request.get({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/health'
})

Example Response

{
    "message": "ok"
}

It’s really easy to see if Juro is experiencing any health related issues. Fingers crossed. Use this to quickly check that your API key is correct and you have access to the API.

HTTP Request

GET /v2/health

TEMPLATES

Templates are a core part of your contract management flow. You should have a template to create your contracts from. No template, no contract it’s that simple.

Get all available templates

Request

request.get({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/templates'
})

Example Response

{
    "templates": [
        {
            "id": "5b30f658715eac2b48fff80b",
            "createdDate": "2018-06-25T14:04:08.804Z",
            "name": "api documentation",
            "status": "published",
            "updatedDate": "2018-06-25T14:20:39.564Z"
        }
    ]
}

You first want to get all templates to correctly select the one that you are going to use to create your contract.

HTTP Request

GET /v2/templates

Get a specific template

Request

request.get({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/templates/:template_id'
})

Example Response

{
    "template": {
        "id": "5b328144e5cd2a0958b488a8",
        "createdDate": "2018-06-26T18:09:08.216Z",
        "name": "api documentation",
        "status": "published",
        "updatedDate": "2018-06-26T18:17:35.916Z",
        "blocks": [
            {
                "uid": "1530036573718_d2f6ee8fbd5d4476b10274abbd15c395",
                "type": "table",
                "rows": [
                    [
                        {
                            "value": "first header"
                        },
                        {
                            "value": "second header"
                        },
                        {
                            "value": "third header"
                        }
                    ]
                ]
            },
            {
                "counterpartySignaturesCaption": "Counterparty block upper caption",
                "type": "signature",
                "uid": "1530036577112_64154a741eba4b5e9cb054254f12d5ff",
                "userSignaturesCaption": "User block upper caption",
                "counterpartySignatures": [
                    {
                        "lowerText": "Counterparty signature lower text",
                        "upperText": "Counterparty signature upper text",
                        "uid": "5b328177e5cd2a0958b488fc"
                    }
                ],
                "userSignatures": [
                    {
                        "lowerText": "User signature lower text",
                        "upperText": "User signature upper text",
                        "uid": "5b328177e5cd2a0958b488fb"
                    }
                ]
            }
        ],
        "fields": [
            {
                "uid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
                "type": "text",
                "title": "Counterparty Legal Name"
            },
            {
                "uid": "1530037019988_3505bc35a96e4657a12a7cbecf304d9d",
                "type": "choice",
                "title": "Yes or no?",
                "choices": [
                    {
                        "value": "Yes"
                    },
                    {
                        "value": "No"
                    }
                ]
            }
        ],
        "questions": [
            {
                "uid": "1530036548215_44faed190f3c4bb4b191f48af588073e",
                "isCounterpartyQuestion": true,
                "isRequired": true,
                "isUserQuestion": false,
                "text": "This is to help us verify your identity and for security reasons",
                "title": "For access, please confirm your name"
            },
            {
                "uid": "1530036548215_fb098a3f669e4a34b45de1fdb4959be3",
                "isCounterpartyQuestion": true,
                "isRequired": true,
                "isUserQuestion": false,
                "text": "This is the email address that we will send the signed contract to",
                "title": "What is your email address?"
            },
            {
                "uid": "1530036548214_4e68c738a2dd45e984655bfc8f90cf88",
                "fieldUid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
                "isCounterpartyQuestion": false,
                "isRequired": true,
                "isUserQuestion": true,
                "title": "What is the legal name of the other party?"
            }
        ]
    }
}

This endpoint retrieves a specific template.

HTTP Request

GET /v2/templates/:template_id

Response Body

Field Description
id template id
createdDate template creation date
name template name
status template status: edit in progress or published
updateDate date when template was last updated
blocks list of template block items
fields list of template field items
questions list of template question items

CONTRACTS

Create a contract

Request

request.post({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts',
    json: {
        "templateId": "5b328144e5cd2a0958b488a8",
        "answers": [
            {
                "uid": "1530036548214_4e68c738a2dd45e984655bfc8f90cf88",
                "value": "Pichael Mennington"
            }
        ]
    }
})

Example Response

{
    "contract": {
        "id": "5b32a2dfbd38141b280b1f8e",
        "contractPreviewUrl": "http://localhost:3000/pdf/934d9046b549a8b2ce7da630dcb2424a",
        "contractUserUrl": "http://localhost:3000/sign/5b32a2dfbd38141b280b1f8e",
        "createdDate": "2018-06-26T20:32:31.426Z",
        "pdfDownloadUrl": null,
        "state": {
            "isSigned": {
                "owner": "not_signed",
                "counterparty": "not_signed"
            }
        },
        "status": "draft",
        "statusFormatted": "Draft",
        "updatedDate": "2018-06-26T20:32:32.494Z",
        "fields": [
            {
                "uid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
                "value": "Pichael Mennington"
            },
            {
                "uid": "1530037019988_3505bc35a96e4657a12a7cbecf304d9d",
                "value": "Yes"
            }
        ],
        "blocks": [
            {
                "uid": "1530036573718_d2f6ee8fbd5d4476b10274abbd15c395",
                "type": "table",
                "rows": [
                    [
                        {
                            "value": "first header"
                        },
                        {
                            "value": "second header"
                        },
                        {
                            "value": "third header"
                        }
                    ]
                ]
            },
            {
                "counterpartySignaturesCaption": "Counterparty block upper caption",
                "type": "signature",
                "uid": "1530036577112_64154a741eba4b5e9cb054254f12d5ff",
                "userSignaturesCaption": "User block upper caption",
                "counterpartySignatures": [
                    {
                        "lowerText": "Counterparty signature lower text",
                        "upperText": "Counterparty signature upper text",
                        "uid": "5b328177e5cd2a0958b488fc",
                        "signingUrl": "http://localhost:3000/counterparty/sign/7710938ceae078446aa77d0785cb8303"
                    }
                ],
                "userSignatures": [
                    {
                        "lowerText": "User signature lower text",
                        "upperText": "User signature upper text",
                        "uid": "5b328177e5cd2a0958b488fb",
                        "username": "[email protected]"
                    }
                ]
            }
        ]
    }
}

This endpoint creates a contract.

Let’s create a contract based on an example template. In example template we have just one template question set as required, in this case it’s an absolute minimum of inputs we should provide in order to create a contract.

HTTP Request

POST /v2/contracts

Body

Parameter Required Description
templateId * id of template
answers list of contract answer for template question
blocks list of contract block items
fields list of contract field items

Response Body

Parameter Description
id id of contract
contractPreviewUrl public link that does not require authentication in order to view the contract
contractUserUrl contract link for authenticated Juro users
createdDate contract creation date
pdfDownloadUrl public link to download PDF. This link will not be available right when you create a contract. This link will be populated only after PDF will be generated, which can be done by either initiating generate PDF procedure in our user interface or when contract was fully_signed
state object describing in which state contract is currently revolving, it can have multiple states e.g. - it can be that contract was partially signed by user and not signed by counterparty
status unlike state, status is indicating only last action performed upon contract
updatedDate when contract was last updated
fields list of contract field items
block list of contract block items

Get a specific contract

Request

request.get({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id'
})

This endpoint retrieves a specific contract.

HTTP Request

GET /v2/contracts/:contract_id

Path params

Parameter Required Description
contract_id * The ID of the contract to retrieve

Response body

For response body please refer to Create a contract

Update a contract

Request

request.patch({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id',
    json: {
        "fields": [
            {
                "uid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
                "value": "Pichael Mennington"
            }
        ],
        "blocks": [
            {
                "uid": "1530036573718_d2f6ee8fbd5d4476b10274abbd15c395",
                "type": "table",
                "rows": [
                    [
                        {
                            "value": "1st header"
                        },
                        {
                            "value": "2nd header"
                        },
                        {
                            "value": "3rd header"
                        }
                    ]
                ]
            },
            {
                "counterpartySignaturesCaption": "Counterparty upper caption",
                "type": "signature",
                "uid": "1530036577112_64154a741eba4b5e9cb054254f12d5ff",
                "userSignaturesCaption": "User upper caption",
                "counterpartySignatures": [
                    {
                        "lowerText": "Counterparty lower text",
                        "upperText": "Counterparty upper text",
                        "uid": "5b328177e5cd2a0958b488fc",
                        "email": "[email protected]"
                    }
                ],
                "userSignatures": [
                    {
                        "lowerText": "User lower text",
                        "upperText": "User upper text",
                        "uid": "5b328177e5cd2a0958b488fb",
                        "username": "[email protected]"
                    }
                ]
            }
        ]
    }
})

This endpoint updates an existing contract.

HTTP Request

PATCH /v2/contracts/:contract_id

Path params

Parameter Required Description
contract_id * The ID of the contract to make update request

Body

Parameter Required Description
blocks list of contract block items
fields list of contract field items

Response body

For response body please refer to Create a contract

Delete a contract

Request

request.delete({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id'
})

Example Response

{
    "message": "ok"
}

This endpoint deletes a specific contract.

HTTP Request

DELETE /v2/contracts/:contract_id

Path params

Parameter Required Description
contract_id * The ID of the contract to delete

Sign your contract

Request

request.post({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id/sign',
    json: {
        "signatureBase64": "iVBORw0KGgoAAAANSUhEUgAAAGYAAAAdCAIAAADXWI43AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0Ad5mH3gAAAFISURBVGhD7ZnRDYMgEIaxT46gb7qdmziGbqEjuUVLvWtDRQzIHTTAl7RapD39+QKximd+LMvSdZ1QGIYBj1lQyRd+Lxvatt22DT+ItzS4Z8cDt6mzrmvf99WOmpf0C/esycWyg1nAvWtP2TKTWcANv4CULSM0SyVNy8AvQrNU0rTMc028Jh3LCNfEa9KxjGnm0qG07DvO8n2eZ2zlh3XmOkGOAxWHuxBANk7ThD14aJoGi+1gKxuUBcZxxLP+pa5r7EGHfp8ISLOwBxv0Y2IKTkJo3MEsAI8xw1tG+oVX88HHOJNZQAC/AN7ITo277VpEs1TClVSNc3Ut4sylEy4ynzku8Jp4Tejy+uwGmLzz/AeVg9CRXbhmA/5KVOKfhMk7neh+AfEjs/HuT8ICcnxc4kkuj0sIKZE5UyJzpkTmTInMmRKZI0K8ACrnnbIVcC8uAAAAAElFTkSuQmCC"
    }
})

Example Response

{
    "message": "ok"
}

This endpoint allows for signing of a contract.

HTTP Request

POST /v2/contracts/:contract_id/sign

Path params

Parameter Required Description
contract_id * The ID of the contract to sign

Body

Parameter Required Description
signatureBase64 * signature image encoded in base64

Send your contract for countersigning

Request

request.post({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id/sign/request',
    json: {
        "counterpartySignatures": {
            "message": "We have best contracts, you should sign them!"
        }
    }
})

Example Response

{
    "message": "ok"
}

You can send a contract for countersigning with this. Cool, right?

HTTP Request

POST /v2/contracts/:contract_id/sign/request

Path params

Parameter Required Description
contract_id * The ID of the contract

Body

Parameter Required Description
message * message in email body that will accompany the countersigning request

Download a PDF of your contract

Request

request.get({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id/pdf/binary'
})

Example Response

content-disposition: attachment; filename="Pichael Mennington + Juro contract.pdf"
content-type: application/pdf
status: 200

binary data

This endpoint allows to download a pdf version of your contract.

HTTP Request

POST /v2/contracts/:contract_id/pdf/binary

Path params

Parameter Required Description
contract_id * The ID of the contract

Start an approval process of your contract

Request

request.post({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id/approval',
    json: {
        "message": "We have best contracts, you should approve them!"
        "approvers": [
            {
                "username": "[email protected]"
            }   
        ]
    }
})

Example Response

{
    "message": "ok"
}

You can start an approval process of your contract by sending to internal Juro users or external persons

HTTP Request

POST /v2/contracts/:contract_id/approval

Path params

Parameter Required Description
contract_id * The ID of the contract

Body

Parameter Required Description
message * message in email body that will accompany the approval process request
approvers * list of approver items

Cancel an approval process of your contract

Request

request.delete({
    headers: { 'x-api-key': <API_KEY> },
    url: 'https://api.juro.io/v2/contracts/:contract_id/approval'
})

Example Response

{
    "message": "ok"
}

Cancel an approval process if you are feeling like it’s taking too long or want to send to another approver

HTTP Request

DELETE /v2/contracts/:contract_id/approval

Path params

Parameter Required Description
contract_id * The ID of the contract

ENTITY TYPES

Signature template block

{
    "counterpartySignaturesCaption": "Counterparty block upper caption",
    "type": "signature",
    "uid": "1530036577112_64154a741eba4b5e9cb054254f12d5ff",
    "userSignaturesCaption": "User block upper caption",
    "counterpartySignatures": [
        {
            "lowerText": "Counterparty signature lower text",
            "upperText": "Counterparty signature upper text",
            "uid": "5b328177e5cd2a0958b488fc"
        }
    ],
    "userSignatures": [
        {
            "lowerText": "User signature lower text",
            "upperText": "User signature upper text",
            "uid": "5b328177e5cd2a0958b488fb"
        }
    ]
}

A signature template block looks like this:

Table template block

{
    "uid": "1530036573718_d2f6ee8fbd5d4476b10274abbd15c395",
    "type": "table",
    "rows": [
        [
            { "value": "first header" },
            { "value": "second header" },
            { "value": "third header" }
        ]
    ]
}

Table in Juro is more like grid than a table, meaning it doesn’t have headers, just a two-dimensional array of rows and columns in it, making it easier to utilize table api.

A table template block looks like this:

Template field

{
    "uid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
    "type": "text",
    "title": "Counterparty Legal Name"
}

A template field looks like this:

Template question

{
    "uid": "1530036548214_4e68c738a2dd45e984655bfc8f90cf88",
    "fieldUid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
    "isCounterpartyQuestion": false,
    "isRequired": true,
    "isUserQuestion": true,
    "title": "What is the legal name of the other party?"
}

A template question looks like this:

Signature contract block

{
    "counterpartySignaturesCaption": "Counterparty block upper caption",
    "type": "signature",
    "uid": "1530036577112_64154a741eba4b5e9cb054254f12d5ff",
    "userSignaturesCaption": "User block upper caption",
    "counterpartySignatures": [
        {
            "lowerText": "Counterparty signature lower text",
            "upperText": "Counterparty signature upper text",
            "uid": "5b328177e5cd2a0958b488fc",
            "email": "[email protected]",
            "name": "Pichael Mennington",
            "signingUrl": "http://localhost:3000/counterparty/sign/fa9300c262eeb3772adf50932e2b9474"
        }
    ],
    "userSignatures": [
        {
            "lowerText": "User signature lower text",
            "upperText": "User signature upper text",
            "uid": "5b328177e5cd2a0958b488fb",
            "username": "[email protected]"
        }
    ]
}

A signature contract block looks like this:

Table contract block

For contract template block please refer to Table template block

Contract field

{
    "uid": "1530036548211_2cc498d4c72e442a81d0caeb709bbec3",
    "value": "Pichael Mennington"
}

A contract field is a slim version of template field and looks like this:

Contract answer

{
    "uid": "1530036548214_4e68c738a2dd45e984655bfc8f90cf88",
    "value": "Pichael Mennington"
}

A contract answer is an answer to the template question. contract answer is used when creating a contract and value provided to the contract answer will populate contract field linked to the particular template question through fieldUid property

Approver

{
    "email": "[email protected]",
}

An approver item represents an internal Juro user or external person. Email or username field should be populated, both fields cannot be populated at the same time.

WEBHOOKS

Webhooks provides an easy way to receive asynchronous events. This allows you to receive push notifications for contract events as they happen in an account.

Events

Example contract event body

{
  "contract": {
    "id": "59787a66cb76170c303ab452",
    "status": "DRAFT"
  },
  "event": {
    "createdDate": "2017-07-26T11:29:43.549Z",
    "type": "contract.edit",
    "author": "Pichael Mennington"
  }
}

We are providing all the relevant events associated with the currently exposed lifecycle of the contract. A more exhaustive list of events hapenning to your account and all related entities associated with it can be found in the activities section of the application. We will be rolling out additional events as we further develop the API.

ERRORS

The Juro API uses the following error codes:

Error Code Meaning
400 Bad Request – Bad request body
401 Unauthorized – Your API key is wrong
403 Forbidden – Cannot perform action at this moment
404 Not Found – Entity not found
405 Method Not Allowed – Method Not Allowed
412 Incompatible state – Entity state is incompatible to perform requested action
429 Too Many Requests – Too Many Requests
500 Internal Server Error – Something went wrong. Try again later.