API Reference NAV
shell

iAgree API

Requests, responses

The API calls are organized around REST. Our API is predictable, uses HTTP response codes (2xx, 4xx, 5xx) to indicate API results/errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Basic Authentication

curl https://<secret-token>:@iagree.com.au/api/<query>
curl -X POST https://<secret-token>:@iagree.com.au/api/<action>

Authenticate your account when using the API by including your secret API token in the request.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. API requests without authentication will fail.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Parameter Description
secret-token Your unique token, provided by us

Contracts

Creating a contract can be done with a single API call, and after that the user can be navigated to the contract form page. Users can provide further details for the contract, can preview the content and send it out for signatures. Webhook notifications are triggered when contracts get signed by all parties.

Lifecycle of a contract:

  1. Contract is created via the API
  2. User is driven to the contract form page (contract_url)
  3. User clicks the Send button to collect online signatures
  4. Once all signatures are collected, the final contract is emailed to all parties, and the webhook notification is triggered.

Creating a contract

POST /api/companies/{company_id}/contracts HTTP/1.1

JSON request parameters

{
  "contract_template_id": "4templ44-6666-3333-4444-555555555555",
  "owner": {
    "email": "mandy@propertymanagement.com"
  },
  "signers": [
    {
      "name": "Sam Signer",
      "email": "sam@tenants.com"
    }
  ],
  "custom_fields": [
    {
      "key": "tenant_name_1",
      "value": "John Doe"
    },
    {
      "key": "property_address",
      "value": "69 Yonge St"
    },
    {
      "key": "rental_amount_per_week",
      "value": "400"
    },
    {
      "key": "commencement_date",
      "value": "2017-07-23"
    }
  ]
}

JSON response

{
  "status": "queued",
  "data": {
    "contract": {
      "contract_id": "1contr11-2222-3333-4444-555555555555",
      "status": "draft",
      "company_id": "8comp888-2222-3333-4444-555555555555",
      "template_name": "Residential Tenancy Agreement",
      "title": "69 Yonge St",
      "contract_url": "https://iagree.com.au/contracts/1contr11-2222-3333-4444-555555555555",
      "owner": {
        "name": "Mandy Manager",
        "email": "mandy@propertymanagement.com"
      },
      "signers": [
        {
          "signer_id": "6signer6-9999-2222-4444-111111111111",
          "name": "Sam Signer",
          "email": "sam@tenants.com"
        }
      ]
    }
  }
}

Example request

curl -X POST https://<secret-token>:@iagree.com.au/api/companies/8comp888-2222-3333-4444-555555555555/contracts -d '{"contract_template_id": "4templ44-6666-3333-4444-555555555555","owner":{"email":"mandy@propertymanagement.com"},"signers":[{"name":"Sam Signer","email":"sam@tenants.com","mobile":"+12481234567"}],"custom_fields":[{"key":"tenant_name_1","value":"John Doe"}]}'

This request creates the contract, and returns the contract_url where the user can be redirected to preview and send the contract.

Url Parameter Required Description
company_id yes The secret key of a company, registered by iAgree. The secret key can be found on the API Credentials page (top right corner), when logged into iAgree, with the appropriate permissions.
Parameter Required Description
contract_template_id yes Specifies the template to be used for the contract (the template_id can be found on the API Credentials page (top right corner), when logged into iAgree, with the appropriate permissions)
owner yes The owner of the contract, who sends it to the signers
owner:email yes The email address of the contract owner, registered in iAgree
signers no List of signers
signers:name Name of the signer
signers:email Email address of the signer - for identification purposes
custom_fields no List of texts to replace in the template
custom_fields:key The “key” is specified in the template
custom_fields:value The text to insert in the contract for the given custom field
Response field Description
status queued
contract:contract_id Id of the contract
contract:template_name Name of the template the contract is based on
contract:title Title of the contract, most often the property address
contract:contract_url The users can access the contract at this address, before and after sending it too.
contract:owner The owner of the contract in iAgree
contract:owner:name The name of the contract owner
contract:owner:email The email address of the contract owner
contract:signers:signer_id Id of the signer
contract:signers:name Name of the signer
contract:signers:email Email of the signer

Querying contract details

GET /api/companies/<company_id>/contracts/<contract_id> HTTP/1.1

JSON response

{
  "data": {
    "contract": {
      "contract_id": "1contr11-2222-3333-4444-555555555555",
      "status": "draft",
      "company_id": "8comp888-2222-3333-4444-555555555555",
      "template_name": "Residential Tenancy Agreement",
      "title": "69 Yonge St",
      "contract_url": "https://iagree.com.au/contracts/1contr11-2222-3333-4444-555555555555",
      "contract_pdf_url": "https://pdf-address.com/expiring-token",
      "owner": {
        "name": "Mandy Manager",
        "email": "mandy@propertymanagement.com"
      },
      "signers": [
        {
          "signer_id": "6signer6-9999-2222-4444-111111111111",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "events": [
            {
              "event": "contract_sent",
              "timestamp": "2017-10-22T18:19:35.979"
            }
          ]
        }
      ]
    }
  }
}

Example request

curl -X GET https://<secret-token>:@iagree.com.au/api/companies/8comp888-2222-3333-4444-555555555555/contracts/1contr11-2222-3333-4444-555555555555

Returns the details of a contract, the details of the signers, including the contract events, the signer events.

Response field Description
contract:contract_id Id of the contract
contract:status draft / sent / signed / withdrawn
contract:template_name Name of the template
contract:template_name Name of the template the contract is based on
contract:title Title of the contract, most often the property address
contract:contract_url The users can access the contract at this address, before and after sending it too.
contract:contract_pdf_url When the contract is signed, the finalized PDF can be accessed via this url. Expires in 24 hours following the request. (as part of the json response, this string might be encoded)
contract:owner The owner of the contract in iAgree
contract:owner:name The name of the contract owner
contract:owner:email The email address of the contract owner
contract:signers:signer_id Id of the signer
contract:signers:name Name of the signer
contract:signers:email Email of the signer
contract:signers:events Events of the signer
contract:signers:events:event contract_sent, reminder_emailed, contract_viewed, contract_email_failed, sms_code_validated, sign_contract, final_contract_sent, witness_signed
contract:signers:events:timestamp Time of the event

Withdrawing a contract

Withdrawn contracts can’t be signed any more, and signed contracts can’t be withdrawn. Draft contracts get deleted upon this request.

POST /api/companies/<company_id>/contracts/<contract_id>/withdraw HTTP/1.1

JSON response

{
  "status": "queued"
}

Example request

curl -X POST https://<secret-token>:@iagree.com.au/api/companies/8comp888-2222-3333-4444-555555555555/contracts/1contr11-2222-3333-4444-555555555555/withdraw
Response field Description
status ‘queued’

Webhooks

Use webhooks to be notified about events that happen real-time. Creating a webhoook endpoint on your server means simply accepting POST requests at a given URL. Webhook data is sent as JSON in the POST request body.

If a webhook is not successfully received (not 2xx response code), iAgree will continue trying to send the webhook once an hour for up to six times.

Contract sent

JSON body

{
  "status": "contract-sent",
  "data": {
    "contract": {
      "contract_id": "1contr11-2222-3333-4444-555555555555",
      "status": "sent",
      "company_id": "8comp888-2222-3333-4444-555555555555",
      "template_name": "Residential Tenancy Agreement",
      "title": "69 Yonge St",
      "contract_url": "https://iagree.com.au/contracts/1contr11-2222-3333-4444-555555555555",
      "contract_pdf_url": "https://pdf-address.com/expiring-token",
      "owner": {
        "name": "Mandy Manager",
        "email": "mandy@propertymanagement.com"
      },
      "signers": [
        {
          "signer_id": "6signer6-9999-2222-4444-111111111111",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "events": [
            {
              "event": "contract_sent",
              "timestamp": "2017-10-22T18:19:35.979"
            }
          ]
        }
      ]
    }
  }
}

This webhook notification is triggered, when the contract is sent to the signers to collect signatures.

Contract signed

JSON body

{
  "status": "contract-signed",
  "data": {
    "contract": {
      "contract_id": "1contr11-2222-3333-4444-555555555555",
      "status": "signed",
      "company_id": "8comp888-2222-3333-4444-555555555555",
      "template_name": "Residential Tenancy Agreement",
      "title": "69 Yonge St",
      "contract_url": "https://iagree.com.au/contracts/1contr11-2222-3333-4444-555555555555",
      "contract_pdf_url": "https://pdf-address.com/expiring-token",
      "owner": {
        "name": "Mandy Manager",
        "email": "mandy@propertymanagement.com"
      },
      "signers": [
        {
          "signer_id": "6signer6-9999-2222-4444-111111111111",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "events": [
            {
              "event": "contract_sent",
              "timestamp": "2017-10-22T18:19:35.979"
            }
          ]
        }
      ]
    }
  }
}

This webhook notification is triggered once every signer has signed the contract. It returns the generatede PDF file.

Contract withdrawn

JSON body

{
  "status": "contract-withdrawn",
  "data": {
    "contract_id": "1contr11-2222-3333-4444-555555555555"
  }
}

This webhook notification is triggered, when the contract is withdrawn.

Retrieving webhook notifications (debug)

GET /api/webhook_notifications HTTP/1.1

The following request helps accessing the last 200 webhook notifications, for debugging purposes.

JSON response

{
  "data": {
    "webhook_notifications":
      [
        {
          "request":{"status":"contract-sent","data":{"contract":{"contract_id":"74192ce4-741c-4750-8d15-e339b849cf96"}}},
          "timestamp":"2017-05-29T02:54:47.299+10:00"
        }
      ]
  }
}