Welcome

Welcome to the Rundl API reference.

With the Rundl API you can connect your applications with the network of people, companies, services and data around you business processes. Create a collaborative community of your teams, customers and partners to bridge boundaries that constrain business processes. Find out more about process collaboration done the Rundl way here.

At Rundl we build our client apps on the same public API that we document here. That means we're committed to its ongoing development, making it feature rich, clean and consistent. We welcome you to leverage the Rundl API in your applications too. Please get in touch via support@rundl.com if you need help or have questions about how to get started.

Create an account for API access

To begin, sign up to create a standard Rundl user account.

After you create your user account, next create a group account. Currently the API is only accessible with a Rundl group account.

To learn more about using Rundl, visit our support site at https://support.rundl.com.

Basics

REST API

The Rundl API is a RESTful Web API, providing programmatic access to resources representing relevant concepts on our platform. It includes URLs to access resources, leveraging built-in HTTP features to handle requests and return responses.

Contact support@rundl.com to register for API access. Registration is currently a manual process.

Event Subscriptions

Rundl Event Subscriptions is a callback solution that enables your application to be called when an event of interest occurs on the platform. The solution involves subscribing to particular event types, which are sent to a target service in your own infrastructure that you manage.

An AWS SNS topic is our first target (we envisage a range of different targets in future, including a HTTP end-point).

Contact support@rundl.com to subscribe to Rundl Events. Subscription is currently a manual process.

Rundl will trigger sending events in 10 second intervals.

Embedded Apps

You can embed your custom HTML web app in an iframe container that's loaded in our web app. Your app can load in a sidebar within a rundl for presentation layer integration of your app.

An embedded app gets unique OAuth credentials upon registration, and is configured with an HTTP end-point where your embedded app resides, and your public key. Contact support@rundl.com to register an embedded app. Registration is currently a manual process. Please provide the url for your app.

After we've registered your app we will also provide a public key.

You can link to your embedded app in our web app using the following internal link format in a rundl message, comment or step description:

[Your embedded page link](!{rundl.id},addon_embeddedpage,your_app_id)

Our web app will automatically resolve this link in Rundl activity as:

<a href="https://stage-go.rundl.com/rundls/123456?sb=addon_embeddedpage&sb_app=123456">Your embedded page link</a>

The token will include a JWT structured like this:

{
  "app_data": "{\"account_id\":\"123456\",\"rundl_id\":\"123456\"}",
  "code": "NnlNIO1B3OiigddIXEkGWHvhVKBESWNFTGQHxbZzJCnSA",
  "algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512",
  "nbf": 1542698558,
  "exp": 1574234558,
  "iat": 1542698558,
  "iss": "stage-go.rundl.com",
  "aud": "https://your-example-uri.com/some-path"
}

When a rundl participant clicks the link, our web app will send a GET request to your HTTP end-point with a JWT sent in the token url parameter.

https://your-example-uri.com/some-path?token=<JWT>

The JWT is signed and the public key we provide after registration can be used to verify the authenticty of the request. The JWT also includes information that allows you to establish a session for a user when further interactions with the Rundl REST API are required.

Your end-point should return valid HTML that will be loaded in the iframe.

Environments

The API can be accessed from our staging and live environments:

https://stage-go.rundl.com/api

https://go.rundl.com/api

Initially we'll give you access to our staging environment to start your integration with Rundl. Request to register an app and we'll supply an integration key/secret for your application in our staging environment.

Authorisation and security

You can authorise against the API using an OAuth2 access token. OAuth2 tokens are acquired programmatically and issuing tokens requires authentication. Read more about Authentication below.

Tokens are used to determine whether the appropriate authorisation has been achieved to access a requested resource. For access to user data, you're app will need to acquire a user access token. In server-to-server scenarios, your app can pass a client access token (note that not all data can be accessed with a client access token).

Versioning

The Rundl API doesn't currently implement versioning. We plan to implement a date-based version strategy in future that will slot in seamlessly.

Requests

Rundl is an SSL-only API.

CORS requests are supported.

UTF-8 character encoding is supported in requests and responses.

The content type being passed to the API for all requests is application/json. Supply the following header with your requests: Content-Type: application/json

Accounts

Understanding Rundl accounts is an important part of using the API.

A user may have multiple account scopes in a single session on Rundl. For example, a user will always have their personal account, and additionally, may be part of a group account (typically, a group account for their company). Therefore, most APIs on Rundl require passing an account parameter. This parameter reflects the user's current account, which is the account scope to use when making a request. Importantly, a user's authorisations will most likely differ depending on their account.

Rate limits

Rundl does not currently apply rate limiting. We do log all API requests and monitor usage to ensure that we have sufficient resources to support the needs of all Rundl integrated client applications.

Pagination

To specify the number of items in a list, use the count query parameter:

curl https://stage-go.rundl.com/api/activity?account=123456&count=12 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>'

In the Rundl API you'll come across list endpoints, like lists of activity, rundls, services or reminders.

By default most list endpoints return a maximum of 100 items per page. However, you can specify the number of items in the response by passing a count parameter in the request URL (but you can't exceed 100 items per page).

The above request returns a paging object as part of the response (example json truncated for brevity):

{
  "data":[
    {...}
  ],
  "object":"list",
  "paging":{
    "next":"https:\/\/stage-go.rundl.com\/api\/activity?account=123456&cursor=9a0c1d45d46",
    "previous":"https:\/\/stage-go.rundl.com\/api\/activity?account=123456&cursor=f5d8f4e51aa",
    "strategy":2
  }
}

When the response has more items than the initial page, you can paginate through the results.

Some list endpoints have outdated limiting parameters, and we'll document these where relevant. However the Rundl API now offers pagination via the concept of cursors. These are special tokens that function as markers in a series. If a list endpoint supports cursor-based pagination you'll receive an extra paging object as part of the response.

To move forwards or backwards through the pages send the next or previous cursor to the endpoint.

Some lists can be ordered by specifying a sort parameter to the end point. Check the documentation for a specific endpoint to tell if it can be ordered. Some endpoints have outdated sorting parameters, and we'll document these where relevant.

Parameter	Description
count	Optional. The number of items to return per page. Defaults number of items is 10. -1 means all. Maximum number of items is usually 100.
cursor	Pointer to the next or previous page in the result set.
sort	Comma separated array of strings e.g. sort=-updated_date. Names need to be top-level atomic resource attributes. Plus (+) means ascending and is the default. Minus (-) means descending. Sorting is best effort and if something is not found it's ignored. Note: Requires URL encoding.

Expanding objects

To retrieve related objects as part of a single request, use the expand query parameter:

curl https://stage-go.rundl.com/api/messages/23420341?account=123456&context_mode=insensitive&expand=comments%2Clinks%2Cfiles%2Creminders \
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>'

The above request returns an expanded message object as part of the response (example json truncated for brevity):

{
  "id":23420341,
  "object":"message",
  "comments":{
    "data":[
      {
        "id":23420441,
        "object":"comment",
        "message_id":23420341,
        "metadata":{ ... },
        "text":"Hi, This is a comment. Thanks"
      }
    ],
    "object":"list",
    "paging":{ ... }
  },
  "distribution_mode":1,
  "files":{
    "data":[
       { ... }
    ],
    "object":"list",
    "paging":{ ... }
  },
  "links":{
    "data":[ ... ],
    "object":"list",
    "paging":{ ... }
  },
  "metadata":{ ... },
  "pin":null,
  "primary_related_entity":{ ... },
  "reminders":{
    "data":[
      { ... }
    ],
    "object":"list",
    "paging":{ ... }
  },
  "text":"Hi, This is a message. Thanks"
}

Expanding objects allows you to retrieve related objects as part of a single request.

For example, a message object has related comments, reminders, files and links. These related objects can be retrieved independently via separate requests. However, you can get a message's comments, reminders, files and links along with the message by passing a comma-separated string of related objects in the expand parameter: expand=comments%2Clinks%2Cfiles%2Creminders

Data types

Time stamps

Time stamps are presented in UTC time.

In future, all timestamps will be formatted as ISO 8601 strings. For example: 2016-04-23T18:25:43.511Z

(TODO) Currently API reponses will serialise dates differently.

Format	Description
wcf DateTime JSON	Date object, represented in JSON as "\/Date(number of ticks)\/". See https://msdn.microsoft.com/en-us/library/system.web.script.serialization.javascriptserializer.aspx.

Errors

The API policy is to return a relevant HTTP Error code with an error description.

Authentication

Each request to the Rundl API must be authenticated. Rundl uses OAuth to provide authorised access to resources via its API. OAuth has a number of benefits:

• Users are not required to share their passwords with third party applications.
• Standard libraries available in most application frameworks.

When you register your application we assign it OAuth credentials and send them to you. Contact support@rundl.com to register for API access. Registration is currently a manual process.

Application authentication flow with OAuth

A client application can directly request an access token from the Authorization server by using the client's id and secret to authenticate. The token will represent the client application (instead of a user). Our implementation is modelled on the Client Credentials Grant flow in the OAuth 2 spec.

This flow is useful in the following cases:

• Machine-to-machine calls without the intervention of a user
• Non-user-centric API calls

Step 1: Get client access token

curl -X POST https://stage-go.rundl.com/api/oauth/client_tokens \
  --header 'Content-Type: application/json' \
  --data '
    {
      "grant_type":"client_credentials",
      "scope":"private",
      "client_id":1234,
      "client_secret":"<Client-Secret>"
    }
  '

The above command returns JSON structured like this:

{
    "access_token": "yUwDyJ7x3gn8s...ZSihtsApgy6bnZI",
    "expires": "2018-09-07T05:39:51.4699703Z",
    "refresh_token": null,
    "scope": "private"
}

Request a client access token using the client secret provided to you by Rundl when registering your application.

POST /oauth/client_tokens

Body parameters

Parameter	Default	Description
grant_type	Required. Available grants: client_credentials
scope	Options: private (default) Authorised access to secure private resources.
client_id	Required. The application's client id, provided during application registration.
client_secret	Required. The application's client secret, provided during application registration.
refresh_token	Not implemented.

Error codes

Code	Description
480	Unauthorized - Invalid Client Key/Secret
400	Bad Request - Missing or unsupported parameters

To get a client access token, passing the credentials in the header:

curl -X POST https://stage-go.rundl.com/api/oauth/client_tokens \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <Base64-Encoded-ClientId-Colon-ClientSecret>' \
  --data '
    {
      "grant_type":"client_credentials",
      "scope":"private"
    }
  '

Step 2: Use the client access token

Your application is now authorised to make calls to the Rundl API, to access protected resources on behalf of your application itself, by passing the access token in the Authorization header.

Authorization: OAuth <base64 encoded client access token>

The available REST API resources are documented in this API reference. We also plan to document a number of walkthroughs that explain how to peform common tasks using the API.

User authentication flow with OAuth

A client application can get permission from a user to access protected resources on their behalf. The applications passes control to Rundl, we let the user log in to their chosen account, and pass back control to your application together with an assertion token. The token is linked to the user and your client id and can be exchanged for a user access token.

This is a standard flow in many web applications. By delegating authentication to Rundl your application doesn't have to handle usernames and passwords.

Our implementation is modelled on the Authorisation Code Grant flow in the OAuth 2 spec.

This is useful in the following cases:

• User grants access to the client application to access its protected data.
• Client application makes calls to the Rundl API on behalf of the authorised user.

Every time your application makes an API call it will be issued on behalf of the user. If the user doesn't have permissions to access the requested resource the call will be blocked.

Step 1: Redirect users to the Rundl authorisation page

Send your users to the Rundl authorisation page.

https://stage-go.rundl.com/oauth/authorize

Pass the following query parameters:

Parameter	Description
response_type	Options: code (default) Authorization code grant flow is the only user authorised grant type currently supported.
client_id	The client id you received from Rundl when registering your application.
redirect_uri	The URI in your application where users get sent after a user decides to log in to your application. If not supplied, user will be redirected to https://stage-go.rundl.com/dashboard.
scope	Not implemented.
state	Not implemented.

The page asks the user to log in, before they are redirected back to your application.

Step 2: Handle authorisation response

Rundl will return the user to your specified redirect_uri with the authorisation code as a parameter.

https://example.com/your_redirect_uri?code=<Auth-Code>

Handle the following query parameters:

Parameter	Description
code	The short lived authorisation code.
redirect_uri	Not implemented. Included for verification.
state	Not implemented. Included for verification.
stay_signed_in	Optional parameter passing through the intent of the user for the session length. Support for this will be dropped once refresh token support is added. Your app will be able to implement its own session length strategy.

Step 3: Get user access token from Rundl

curl -X POST https://stage-go.rundl.com/api/oauth/access_tokens \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '
    {
      "grant_type":"authorization_code",
      "client_id":286454,
      "client_secret":"<Client-Secret>",
      "scope":"private",
      "code":"<Auth-Code>"
    }
  '

The above command returns JSON structured like this:

{
    "access_token": "yUwDyJ7x3gn8s...ZSihtsApgy6bnZI",
      "refresh_token": null,
    "expires": "2018-02-07T05:39:51.4699703Z",
    "scope": "private"
}

Exchange the authorisation code for a user access token.

POST /oauth/access_tokens

Body parameters

Parameter	Description
grant_type	Required. Options: authorization_code
client_id	Required - unless passed in the Authorization header. The application's client id, provided during application registration.
client_secret	Required - unless passed in the Authorization header. The application's client secret, provided during application registration.
code	The authorization code returned from Rundl when the user authorises your application to access Rundl on their behalf.
scope	Options: private (default) authorised access to secure private resources, public some resources are available for anonymous access via a public access token
redirect_uri	Not implemented.
state	Not implemented.
refresh_token	Not implemented.
stay_logged_in	Optional parameter passing through the intent of the user for the session length. Options: false (default) access token will expire after 8 hours, true access token will expire after 30 days This parameter will be dropped once refresh tokens are implemented.

Error codes

Code	Description
400	Bad request. e.g. User not enabled for login. Grant type not supported.
480	Revoked client id
498	Token invalid

To get a user access token, passing the credentials in the header:

curl -X POST https://stage-go.rundl.com/api/oauth/access_tokens \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <Base64-Encoded-ClientId-Colon-ClientSecret>' \
  --data '
    {
      "grant_type":"authorization_code",
      "scope":"private",
      "code":"<Auth-Code>"
    }
  '

Step 4: Use the access token

Your application is now authorised to make calls to the Rundl API, to access protected resources on behalf of the authenticated user, by passing the access token in the Authorization header.

Authorization: OAuth <User-Access-Token>

See REST API method reference for information about the the available resources.

Core resources

The gid object

Generic object representing any resource on Rundl

Attribute	Type	Description
id	integer	Unique identifier for the resource.
global_type	integer	Unique identifier for the type of object.
name	string	The name of the resource.

Orders

Overview

Receive new orders for transactional work. Service providers can offer services to their customers and referral partners and track opportunities sent as orders.

The order object

Attribute	Type	Description
id	integer	Unique identifier for the order.
summary	string	Summary of the order.
detail	string	Details about the order, such as a message or description.
sender	object	Order sender as a participant object. Only returned in responses. Use participants attribute when creating orders.
receiver	object	Order receiver as a participant object. Only returned in responses. Automaticallay assiged after creating orders.
referrer	object	Order referrer as a participant object. Only returned in responses. Automaticallay assiged after creating orders. See referrer_code attribute.
state	object	Status of the order. See approval states reference.
referrer_code	string	Code to identify the order referrer.
rundl	object	Information about the rundl that's started when accepting an order. Each order has an associated preliminary rundl to support collaboration on the order.
service	object	Identifies the service being ordered.
metadata	object	Context information related to the order
participants	list	List of participants. Not returned in responses. Attribute only support supplying participants when creating orders.
fields	list	List of fields. Not returned in responses. Attribute only support supplying custom field data when creating orders.
actions	list	List of actions for additional operations on the order. e.g. to associate optional Files or a Real Property where Rundl Property AU addon is enabled for the service.

Order a service

curl -X POST https://stage-go.rundl.com/api/orders?account=123456 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
    {
      "order": {
        "service":{
          "id":23225632
        },
        "summary":"123 Baker St Caulfield (Demo)",
        "detail":"Sale of property at 123 Baker St Caulfield Vic 3126 ",
        "participants":[
          {
            "categories": ["sender"],
            "context":{
              "id":574997
            },
            "roles":["Seller"]
          },
          {
            "contact": {
              "first_name":"Rod",
              "surname":"Montford",
              "email":"rmontford@email.com",
              "mobile":"+61412356789"
            },
            "roles":["Seller"]
          }
        ],
        "actions":[
          {
            "name":"add",
            "id":123456,
            "object":"file"
          },
          {
            "name":"add",
            "id":123456,
            "version":1,
            "object":"realproperty"
          }
        ]
      }
    }
  '

The above command returns JSON structured like this (some objects truncated for brevity):

{
  "id":42704777,
  "object":"order",
  "version":1,
  "version_latest":null,
  "detail":"123 Baker St Caulfield Vic 3126",
  "metadata":{ ... },
  "receiver":{ ... },
  "referrer":{ ... },
  "referrer_code":"yzfZxGNL",
  "rundl":null,
  "sender":{ ...},
  "service":{ ... },
  "state":{ ... },
  "summary":"Sale of property at 123 Baker St Caulfield Vic 3126"
}

Order a service from a Rundl service provider. The user context sending the order must have permission to order the service. Service settings control which contexts can order. Example shows optional actions to attach additional resources such as files or a realproperty.

HTTP Request

POST /orders?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when ordering the service
referrer_code	A code that can be associated with the order. If the code (stored in Rundl against a contact) is assigned a context, the context will be added to the order as referrer.

Request body

See example request.

Files

Overview

Upload files to Rundl before attaching to other entities within the Rundl API. Rundl uses AWS S3 as its file storage backend.

Uploading files is a three-step process:

1. Create an upload_session. An upload_session contains the required short-lived credentials to access AWS S3.
2. Upload the file to AWS S3. Uploading is best done using one of the many AWS SDKs.
3. Update the upload_session to complete the upload.

File categories

Name	Value	Description
unknown	0
logo	1	eg group logo
data	2	data file (eg rundl file, wall file, service resource)
avatar	3	user avatar
design_header	4	branding / design header image
design_content	5	eg Step content image

The upload_session object

Attribute	Type	Description
aws_access_key	string	AWS access key used in signing.
aws_bucket	string	Target AWS bucket name.
aws_region	string	AWS region.
aws_resource_key	string	Target AWS resource key.
aws_secret_key	string	AWS access key used in signing.
aws_session_token	string	AWS access key used in signing.
content_type	string	Mime content type for the file to be uploaded.
file	string	File object for a verified successful upload.
filename	string	Filename with extension (pathless). Note that content-type is derived from the filename extension.
hash	string	MD5 file hash.
publish	boolean	Publish immediately on upload success.
size	integer	File size in bytes.
sstatus	string	The session status.
upload_token	string	Server allocated token identifying the upload session.

Create an upload_session

curl -X POST https://stage-go.rundl.com/api/files/uploadsession?account=123456&target=42980836&category=2 \  
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
    {
      "upload_session": {
        "filename": logo.png,
        "size": 15992
      }
    }
  '

The above command returns JSON structured like this:

{
  "aws_access_key":"ASIAJAY...WXXTCA",
  "aws_bucket":"uploadsrundlco",
  "aws_region":"ap-southeast-2",
  "aws_resource_key":"d419b96c-x111-1111-x11y-7b7706cfdc57",
  "aws_secret_key":"584veUApzU...a57z0AFHp",
  "aws_session_token":"FQoDYXdzEOj//////////wEaDDp8CIKb1dxGiL2hNyK...rNyAw+vZGSPQbCCyoEHStewo177t0QU=",
  "content_type":"image\/png",
  "file":null,
  "filename":"logo.png",
  "hash":null,
  "publish":false,
  "size":15992,
  "status": "pending",
  "upload_token":"d419b96c-x111-1111-x11y-7b7706cfdc57",
}

Create an upload session prior to uploading a file. The upload session will return the parameters required by AWS S3 when uploading a file.

HTTP Request

POST /files/uploadsession?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when uploading the file
target	The id of the entity the file will be associated with e.g. a rundl id.
category	The category of file in Rundl.

Update an upload_session

curl -X PATCH https://stage-go.rundl.com/api/files/uploadsession/d419b96c-b320-4088-b66a-7b7706cfdc57?account=123456 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
    {
      "upload_session":{
        "aws_access_key":"ASIAJAY...WXXTCA",
        "aws_bucket":"uploads.stage.rundl.co",
        "aws_region":"ap-southeast-2",
        "aws_resource_key":"d419b96c-x111-1111-x11y-7b7706cfdc57",
        "aws_secret_key":"584veUApzU...a57z0AFHp",
        "aws_session_token":"FQoDYXdzEOj//////////wEaDDp8CIKb1dxGiL2hNyK...rNyAw+vZGSPQbCCyoEHStewo177t0QU=",
        "content_type":"image/jpeg",
        "file":null,
        "filename":"handshake.jpg",
        "publish":null,
        "size":233106,
        "status":"uploaded",
        "upload_token":"d419b96c-x111-1111-x11y-7b7706cfdc57"
      }
    }
  '

HTTP Request

PATCH /files/upload_sessions/{upload_token}?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when uploading the file

Path parameters

Parameter	Description
upload_token	The token to identify the upload session.

Checkouts

Overview

A checkout represents the attributes of in-app purchase to be made on Rundl. Creating a checkout maybe required before making some in-app purchases. The checkout id is passed as a URL parameter to APIs related to purchase flows.

The checkout object

Attribute	Type	Description
id	integer	Unique identifier for the checkout.
object	string	String representing the object's type. Value is checkout
seller	object	The gid object for the seller's account.
buyer	object	The gid object for the buyer's account.
status	string	Status of the order. See states reference.
product_order	integer	Unique identifier for the product order created after the checkout and subsequent steps in the purchase workflow.
items	list	A list of checkout items.
items_total_price	string	The total price of all the checkout items.
total_tax	string	The total tax of the checkout.
total_price	string	The total price of the checkout including tax.
currency	string	ISO 4217 three-letter code.
payment_account_types	string array	Options: credit_card, manual
payment_token	string	Security token for credit card checkouts
related	integer	unique identifier of the related entity being purchased
service	integer	Unique identifier of the service type related to a rundl checkout
rundl	integer	Unique identifier of the rundl related to the checkout
created_date	string	Date the resource was created.

The (checkout) item object

Attribute	Type	Description
product	object	The product being purchased.
quantity	string	The quantity of the product being purchased.
amount	string	The amount of the checkout item being purchased.
tax_id	integer	Unique identifier for the relevant tax for the checkout item.
tax_amount	string	The amount of tax for the product being purchased.
tax_status	integer	List of participant_lead objects
tax_lines	list	List of tax_line items
reference	list
data	integer

The product object

Attribute	Type	Description
id	integer	Unique identifier for the product.
object	string	String representing the object's type. Value is product
name	string	The name of the product.
price	string	The price of the product.
currency	string	ISO 4217 three-letter code.

The tax_line object

Attribute	Type	Description
amount	integer	The percentage amount of the tax.
name	string	The name of the tax.

Create a checkout

curl -X POST https://stage-go.rundl.com/api/checkouts?account=17357980 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <Base64-Encoded-User-Access-Token>' \
  --data '
    {
      "checkout": {
        "service": 30798101,
        "payment_token": null,
        "items": [
          {
            "product": {
              "id": 30798131
            },
            "quantity": 1
          }
        ]
      }
    }
  '

The above command returns JSON structured like this:

{
  "id": 30799601,
  "object": "checkout",
  "buyer": {
    "global_type": 0,
    "id": 17357980,
    "name": "World Conveyancing"
  },
  "created_date": "/Date(1532940986653+0000)/",
  "currency": "AUD",
  "items": [
      {
        "amount": 0,
        "data": null,
        "product": {
            "id": 30798131,
            "object": "product",
            "currency": "AUD",
            "name": "kzi68b4 hosted rundl",
            "price": 0
        },
        "quantity": 1,
        "reference": null,
        "tax_amount": 0,
        "tax_id": 30734732,
        "tax_lines": [
            {
              "amount": 0,
              "name": "GST"
            }
        ],
        "tax_status": 1
      }
  ],
  "items_total_price": 0,
  "payment_account_types": [
    "credit_card",
    "manual"
  ],
  "payment_token": null,
  "product_order": null,
  "related": null,
  "rundl": null,
  "seller": {
    "global_type": 0,
    "id": 286896,
    "name": "Rundl Pty Ltd"
  },
  "service": 30798101,
  "status": 0,
  "total_price": 0,
  "total_tax": 0
}

Create a checkout for a product related to a service.

HTTP Request

POST /checkouts?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl

Request body

See example request.

Rundls

Overview

A rundl is a shared digital space that brings together people and information around a business transaction.

The rundl object

Attribute	Type	Description
id	integer	Unique identifier for the rundl.
name	string	The name of the rundl.
description	string	The description of the rundl.
video	string	Ignore. Shouldn't be here.
service	integer	Unique identifier of the type of service for the rundl.
service_name	string	The name of the service
service_profile_banners	list	Object containing sized image urls.
order	integer	Unique identifier for an order, where the rundl was initiated from order flow.
model_id	integer	Unique identifier for service model.
brand_color	string	Hexadecimal colour value. If not set on the rundl, inherits from the service.
profile_banners	list	List of sized image urls.
metadata	object	Context information related to the rundl
state	object	Status of the order. See approval states reference.
last_actioned_step	object	Object representing the step that was last updated.
last_actioned_step_state	object	Object representing the status of the step that was last updated.
last_actioned_step_state_metadata	object	Object with standard metadata relating to the last status update.
percentage_complete	integer
reference	string	Host's own reference for this rundl. Optionally overridden by each participant.
host	string	The host of the rundl. Gid if start, or entity when get.
related_rundls	list	List of related rundls
add_ons	list	Expandable. List of add-ons enabled for this rundl.

Variant rundl object to support start rundl only

Attribute	Type	Description
name
description
host
fields	list	List of fields
subscriptions	list	List of event subscriptions
related_rundls	list	List of related rundl identifiers
files	list	List of Rundl file identifiers. Stage files on auth user's account via the files API prior to sending the order.
participants	list	List of participant objects

Start a rundl

curl -X POST https://stage-go.rundl.com/api/services/24415244/rundls?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
      {
        "rundl":{
          "name":"Sale of property at 123 Baker St Caulfield Vic 3126",
          "description":"Sale of property at 123 Baker St Caulfield Vic 3126",
          "host":{
            "id":2237816
          },
          "participants":[
            {
              "contact":{
                "first_name":"Demo",
                "surname":"User",
                "email":"demo_user@gmail.com",
                "mobile":"+61411111111"
              },
              "roles":[
                "Seller"
              ]
            }
          ],
          "files":[
            42980832
          ]
        }
      }
  '

The above command returns JSON structured like this:

{
  "id":42980836,
  "object":"rundl",
  "version":null,
  "version_latest":null,
  "add_ons":null,
  "brand_color":"#53C876",
  "description":"Sale of property at 123 Baker St Caulfield Vic 3126",
  "host":{
    "id":2237816,
    ...
  },
  "last_actioned_step":null,
  "last_actioned_step_state":null,
  "last_actioned_step_state_metadata":null,
  "metadata":{
    ...
  },
  "model_id":42979888,
  "name":"Sale of property at 123 Baker St Caulfield Vic 3126",
  "order":null,
  "percentage_complete":0,
  "profile_banners":null,
  "reference":null,
  "related_rundls":[],
  "service":42979887,
  "service_name":"Selling your home with Property Agents",
  "service_profile_banners":null,
  "state":{
    ...
  },
  "video":null
}

Start a rundl based on a service. The user context starting the rundl must have permission to start rundls for the service. The chosen host must have permission to host rundls for the service.

HTTP Request

POST /services/{service_id}/rundls?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl

Path parameters

Parameter	Description
service_id	The id of the service being started

Request body

See example request.

Update rundl status

curl -X POST https://stage-go.rundl.com/api/rundls/events?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
      {
        "rundlId":43754936,
        "theEvent":0,
        "utcEffectiveDate":"/Date(1585811350941)/",
        "silent":true
      }
  '

The above command returns JSON structured like this:

{
  "id":42980836,
  "object":"rundl",

}

Update the status of a rundl. The user context must have permission to manage the rundls.

The rundlId attribute is the unique identifier for the rundl to update.

The theEvent attribute determines the new status.

Value	Description
0	Start a rundl. Can be used to re-start a completed or cancelled rundl.
1	Complete a rundl. This status means the process is finished.
2	Cancel a rundl. This status means the transaction is no longer valid.

The utcEffectiveDate attribute overrides the current date-time value. Allows backdating of events where updates in Rundl happen after the real-world event happened.

The silent attribute allows notifications for the event to be suppressed.

HTTP Request

POST /rundls/events?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl

Rundl participants

Overview

Participants are the stakeholders in the business transaction that's getting delivered as a rundl.

The participants API supports adding existing contexts (users, groups, or members and teams within groups) via the context attribute. Contexts can actively participate in rundls. For existing contexts, clients can implement the search API to find existing users/groups. For groups, clients can optionally query the Contexts API to find available member of team contexts for that group.

The participants API also supports inviting a new user by supplying person details and an email address via the contact attribute. A pending user is made the participant context and an invitation to join Rundl is sent to the address. If the receiver accepts the invitation (by clicking the sign up link in the invitation email) the pending user and participant transitions to a full.

The participants API also supports adding passive participant via the contact attribute and setting category to virtual.Virtual participants may be updated to full participants later by setting the category to participant.

The participant object

Attribute	Type	Description
id	integer	The id of the participant.
categories	string array	List of strings to represent participant category. Options: participant, virtual, sender, receiver, referrer
rundl	integer	The id of the rundl the participant is added to.
context	object	The context that is participating. Expandable
contact	object	The contact associated with the participant. Expandable
status	object	Status of the participant.
created_date	The date the participant was added.
roles	string array	Array of role names asigned to the participant.
is_host	boolean	Flag to indicate if participant is the host.
observer	boolean	Flag for making participant an observer.
message	string	Message included in invitation email when adding a participant.
reference	string	The participant's own reference for the rundl they're participating in.

Add a rundl participant

curl -X PUT https://stage-go.rundl.com/api/rundls/123456/participants?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
      {
        "participant":{
          "rundl":42980836,
          "message":"I would like to add you as a participant in \"Sale of property at 123 Baker St Caulfield Vic 3126\".",
          "observer":false,
          "contact":{
            "first_name":"Demo",
            "surname":"User",
            "mobile":"+61411111111",
            "email":"demo_user@rundl.com"
          },
          "roles":[
            "Default"
          ]
        }
      }
  '

The above command returns JSON structured like this:

{
  "id":42980998,
  "object":"participant",
  "version":null,
  "version_latest":null,
  "categories":[
    "virtual"
  ],
  "contact":{
    "id":42980996,
    "object":"contact",
    "version":1,
    "version_latest":1,
    "account_id":1687398,
    "display_name":"Demo User",
    "email":"demo_user@rundl.com",
    "first_name":"Demo",
    "metadata":{
      ...
    },
    "mobile":"+61 411 111 111",
    "referrer_codes":null,
    "state":2,
    "surname":"User"
  },
  "context":null,
  "created_date":"\/Date(1581998394354+0000)\/",
  "is_host":false,
  "message":null,
  "observer":false,
  "order":null,
  "reference":null,
  "roles":[
    "Default"
  ],
  "rundl":42980836,
  "status":1
}

HTTP Request

POST /rundls/{rundl_id}/participants?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl.

Path parameters

Parameter	Description
rundl_id	The id of the rundl the participant is added to.

Request body

See example request.

Update a rundl participant

For example, upgrade a virtual participant to full participant.

curl -X PATCH https://stage-go.rundl.com/api/rundls/123456/participants/25577359?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
      {
        "participant":{
          "categories":[
            "participant"
          ],
          "id":42980998
        }
      }
  '

The above command returns JSON structured like this:

{
  "id":42980998,
  "object":"participant",
  "version":null,
  "version_latest":null,
  "categories":[
    "participant"
  ],
  "contact":{
    "id":42980996,
    "object":"contact",
    "version":1,
    "version_latest":1,
    "account_id":1687398,
    "display_name":"Demo User",
    "email":"demo_user@rundl.com",
    "first_name":"Demo",
    "metadata":{
      ...
    },
    "mobile":"+61 411 111 111",
    "referrer_codes":null,
    "state":2,
    "surname":"User"
  },
  "context":{
    "id":42981002,
    "object":"context",
    "version":null,
    "version_latest":null,
    "account_id":null,
    "content_image_url":null,
    "description":null,
    "global_type":43,
    "name":"Demo User",
    "parent":null,
    "profile_image_urls":null,
    "user_id":null,
    "video_id":null,
    "is_current":null,
    "privacy":null,
    "team_type":null
  },
  "created_date":"\/Date(1581998394354+0000)\/",
  "is_host":false,
  "message":null,
  "observer":false,
  "order":null,
  "reference":null,
  "roles":[
    "Default"
  ],
  "rundl":42980836,
  "status":1
}

Updates the participant's roles or toggles being an observer.

HTTP Request

PATCH /rundls/{rundl_id}/participants/{participant_id}?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl.

Path parameters

Parameter	Description
rundl_id	The id of the rundl the participant is added to.
participant_id	The id of the participant to update.

Request body

See example request.

Remove a rundl participant

To revoke a participant's access to a rundl remove the participant.

curl -X DELETE https://stage-go.rundl.com/api/rundls/123456/participants/25577359?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data ''

Rundl messages

Overview

A rundl message is a communication sent within a rundl to some or all participants. A message may have attached files and links. Permissions can be set to control who can see the message.

The message object

Attribute	Type	Description
id	integer	Unique identifier for the rundl.
text	string	The message content
privacy	integer	Privacy category information.
parent	object	Object representing the parent rundl entity related to the message.
metadata	object	Context information related to the message
pin	object	Information about the pinning of this message in the rundl.
comments	list	Comments attached to the message.
links	list	Links attached to the message.
files	list	Files attached to the message.
reminders	list	Reminders attached to the message.

Post a message

curl -X POST https://stage-go.rundl.com/api/rundls/42980836/messages?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
      {
        "message":{
          "text":"Message here",
          "actions":[
            {
              "name":"add",
              "id":42981063,
              "object":"file"
            }
          ]
        }
      }
  '

The above command returns JSON structured like this:

{
  "id":42981072,
  "object":"message",
  "version":null,
  "version_latest":null,
  "comments":{
    "data":[],
    "object":"list",
    "paging":{
      "next":null,
      "previous":null,
      "strategy":0
    }
  },
  "files":{
    "data":[
      {
        "id":42981063,
        "object":"file",
        "version":4,
        "version_latest":null,
        "category":2,
        "content_type":"image\/jpeg",
        "metadata":{
          ...
        },
        "name":"handshake.jpg",
        "privacy":6,
        "published":true,
        "related_entities":[
          ...
        ],
        "size":233106,
        "status":1,
        "thumb_urls":[
          ...
        ]
      }
    ],
    "object":"list",
    "paging":{
      "next":null,
      "previous":null,
      "strategy":0
    }
  },
  "links":{
    "data":[],
    "object":"list",
    "paging":{
      "next":null,
      "previous":null,
      "strategy":0
    }
  },
  "metadata": {
    ...
  },
  "parent":{
    "id":42980836,
    "object":"entity_identity",
    "version":null,
    "version_latest":null,
    "account_id":null,
    "content_image_url":null,
    "description":"Sale of property at 123 Baker St Caulfield Vic 3126",
    "global_type":32,
    "name":"Sale of property at 123 Baker St Caulfield Vic 3126",
    "parent":null,
    "profile_image_urls":null,
    "user_id":null,
    "video_id":null
  },
  "pin":null,
  "privacy":2,
  "reminders":{
    "data":[],
    "object":"list",
    "paging":{
      "next":null,
      "previous":null,
      "strategy":0
    }
  },
  "text":"dsadsa"
}

Post a message to a rundl. The user context posting the message must have permission to collaborate on the rundl. .

HTTP Request

POST /rundls/{rundl_id}/messages?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl

Path parameters

Parameter	Description
rundl_id	The id of the rundl being posted to

Request body

See example request.

Real estate

Overview

APIs to support real estate transactions, in particular by supporting property data.

Creating a new property involves a the following workflow using real estate endpoints:

1. Use the real_estate/au/addresses/autocomplete endpoint to retrieve a list of address suggestions.
2. Use the real_estate/au/addresses/{uuid} endpoint to retrieve the chosen address. An address record is returned.
3. Use the real_estate/au/properties endpoint with address record id to check for an existing rundlproperty.
4. Use the real_estate/au/properties endpoint to create a new realproperty.

The realproperty object

Attribute	Type	Description
id	integer	Unique identifier for the real property.
address	object	The name of the rundl.
administration_areas	object	The description of the rundl.

The address autocomplete object

Attribute	Type	Description
full_address	string	Full address as one line.
uuid	string	The unique identifier returned by the address lookup service. Rundl uses AddressFinder. If you have your own AddressFinder account you can do the address lookup direct with AddressFinder.

The address object

Attribute	Type	Description
id	integer	Rundl's unique identifier for the address.
object	string	The Rundl object type.
version	integer	The object version.
version_latest	string	Latest version number.
admin_level_1	string	First level administration area. In Australia, state e.g. VIC.
building_name	string	Buidling name
country	string	Country as code e.g. AUS
data_type	string	The address lookup provider e.g. address_finder
dpid	string	AusPost's unique identifier for the address.
full_address	string	28 St Edmonds Road, PRAHRAN VIC 3181",
gnaf_id	string	PSMA's unique identifier for the address.
latitude	string	Latitude coordinate
level	string	Building level,
level_type	string	Type of building level,
locality_level_1	string	First level locality. In Australia, town/subers e.g. PRAHRAN.
longitude	string	Longitude coordinate.
lot	string	Lot number.
non_standard_line_1	string	Address line 1 where address entered as lines.
non_standard_line_2	string	Address line 2 where address entered as lines.
postcode	string	Postcode
street_name	string	Street name
street_number	string	Street number
street_suffix	string	Street suffix e.g. 12 Smith Street 'West'
street_type	string	Type of street.
unit	string	Building unit number.
unit_type	string	Building unit type.
uuid	string	The address lookup provider's unique identifier. Rundnl uses AddressFinder. Note the uuid from AddressFinder changes each time they update their dataset.

Autocomplete address

curl -X GET https://stage-go.rundl.com/api/real_estate/au/addresses/autocomplete?account=123456&address=28%20St%20Edmonds%20Road&index=0&count=25 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \

The above command returns JSON structured like this:

[
  {
    "full_address":"28 St Edmonds Road, PRAHRAN VIC 3181",
    "uuid":"7b21e40e-378e-11ea-9609-68c0611977d0"
  },
  {
    "full_address":"28 St Edmonds Road, ARMADALE VIC 3181",
    "uuid":"c4433c3a-3795-11ea-8b73-68c0629ca78b"
  },
  ...
]

Lookup an address with an address part as search string.

HTTP Request

GET /real_estate/au/properties?account={account_id}&address={text}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl
address	Text to search addresses.

Get address

curl -X GET https://stage-go.rundl.com/api/real_estate/au/addresses/7b21e40e-378e-11ea-9609-68c0611977d0?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \

The above command returns JSON structured like this:

{
  "id":123456,
  "object":"address",
  "version":1,
  "version_latest":null,
  "admin_level_1":"VIC",
  "building_name":null,
  "country":"AUS",
  "data_type":"address_finder",
  "dpid":null,
  "full_address":"28 St Edmonds Road, PRAHRAN VIC 3181",
  "gnaf_id":"GAVIC412129732",
  "latitude":-37.85035600,
  "level":null,
  "level_type":null,
  "locality_level_1":"PRAHRAN",
  "longitude":144.99193600,
  "lot":null,
  "non_standard_line_1":null,
  "non_standard_line_2":null,
  "postcode":"3181",
  "street_name":"St Edmonds",
  "street_number":"28",
  "street_suffix":null,
  "street_type":"Road",
  "unit":null,
  "unit_type":null,
  "uuid":"7b21e40e-378e-11ea-9609-68c0611977d0"
}

Get an address with address autocomplete uuid. The endpoint to be used together with address autocomplete endpoint.

HTTP Request

GET /real_estate/au/addresses/{uuid}?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl

Path parameters

Parameter	Description
uuid	The address autocomplete service's unique id.

Get properties

curl -X GET https://stage-go.rundl.com/api/real_estate/au/properties?account=123456&address_id=42704758 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \

The above command returns JSON structured like this:

{
  "data":[ ... ],
  "object":"list",
  "paging":{
    "next":null,
    "previous":null,
    "strategy":0
  }
}

Get a collection of properties passing the address id as a filter. Use this to check for the existence of a property for the given address.

HTTP Request

GET /real_estate/au/properties?account={account_id}&address_id={address_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl
address_id	The id of an address to filter the collection

Create a realproperty

curl -X POST https://stage-go.rundl.com/api/real_estate/au/properties?account=123456 \ 
  --header 'Content-Type: application/json' \
  --header 'Authorization: OAuth <User-Access-Token>' \
  --data '
    {
      "real_property":{
        "actions":[
          {
            "name":"add",
            "id":123456,
            "object":"address"
          }
        ]
      }
    }
  '

The above command returns JSON structured like this:

{
  "id":123456,
  "object":"realproperty",
  "version":1,
  "version_latest":null,
  "address":{
    "id":123456,
    "object":"address",
    "version":1,
    "version_latest":null,
    "admin_level_1":"VIC",
    "building_name":null,
    "country":"AUS",
    "data_type":"address_finder",
    "dpid":"44418691",
    "full_address":"28 St Edmonds Road, PRAHRAN VIC 3181",
    "gnaf_id":"GAVIC412129732",
    "latitude":null,
    "level":null,
    "level_type":null,
    "locality_level_1":"PRAHRAN",
    "longitude":null,
    "lot":null,
    "non_standard_line_1":null,
    "non_standard_line_2":null,
    "postcode":"3181",
    "street_name":"St Edmonds",
    "street_number":"28",
    "street_suffix":null,
    "street_type":"Road",
    "unit":null,
    "unit_type":null,
    "uuid":"7b21e40e-378e-11ea-9609-68c0611977d0"
  },
  "administration_areas":null
}

Create a new property with an address id. An address is the natural key for the property. Create/retrieve the address using address-related endpoints.

HTTP Request

POST /real_estate/au/properties?account={account_id}

Query parameters

Parameter	Description
account_id	The id of the selected account when starting the rundl

Request body

See example request.