NAV Navbar
shell
  • Welcome
  • Basics
  • Authentication
  • Core resources
  • Orders
  • Files
  • Checkouts
  • Rundls
  • Rundl participants
  • 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 and your public key.

    After we've registered your app, you can link to it 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 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:

    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:

    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:

    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.

    User authentication flow with JWT

    Rundl allows third party applications to authenticate users directly with Rundl using a JSON Web Token (JWT) signed with an RSA key. This authentication method is intended for server-to-server applications.

    Using the JWT flow has a number of benefits:

    Use the JWT flow in the following cases:

    About SSO

    When you attempt to authenticate your application's user for the first time:

    1. A new Rundl user will be created based on the information included in the JWT assertion.
    2. A user access token is returned.

    After the first successful authentication, in subsequent attempts you will simply be returned a user access token.

    There are important conceptual differences with the Rundl user created via this flow:

    Step 1: Register your application as an identity provider

    In addition to the standard requirements for registering your application, you will need to register to become an identity provider. Contact support@rundl.com.

    Step 2: Generate an RSA Keypair

    Run the following commands (for example using Cygwin on Windows).

    Generate private key:

    openssl genrsa -out private_key.pem 2048
    

    Generate public key:

    openssl rsa -pubout -in private_key.pem -out public_key.pem
    

    If generated properly, the RSA public key should look like this:

    -----BEGIN PUBLIC KEY-----
    MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCqGKukO1De7zhZj6+H0qtjTkVxwTCpvKe4eCZ0
    FPqri0cb2JZfXJ/DgYSF6vUpwmJG8wVQZKjeGcjDOL5UlsuusFncCzWBQ7RKNUSesmQRMSGkVb1/
    3j+skZ6UtW+5u09lHNsj6tQ51s1SPrCBkedbNf0Tp0GbMJDyR4e9T04ZZwIDAQAB
    -----END PUBLIC KEY-----
    

    To sign and authenticate a JWT assertion you need to generate a RSA private-public keypair. You will sign your requests with the private key, which is verified by the public key you provide to Rundl. Be sure to protect your private key.

    We suggest generating the keypair using the OpenSSL tool.

    If using other tools, note the following settings:

    Setting Value
    Key length 2048
    Algorithm RS512
    Public key Export asn.1 format

    Step 3: Submit the Public Key

    The public key is not a secret so can be emailed or posted to a rundl. This key is required to be verifiably under the control of the party identified as the issuer of the JWT.

    Step 4: Construct the JWT assertion

    The following table lists libraries that have been used to successfully generate a valid JWT:

    Language Link Settings
    Java https://github.com/auth0/java-jwt
    Relevant sample code:
    com.auth0.jwt.JWTRoundTripRsa256Test
    Key length: 2048 (default)
    Algorithm: options.setAlgorithm(Algorithm.RS512)
    Public key: asn.1 format export.
    C# https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/
    PHP https://github.com/emarref/jwt

    It is likely that other libraries from https://jwt.io/ are also compatible.

    Header attributes

    Parameter Type Description
    alg String Required. The algorithm used to verify the signature. "RS512". 512 represents the SHA-2 hashing algorithm that is used by the digital signature.
    typ String Required. Type of token. Default is “JWT” to specify a JSON Web Token (JWT).

    Payload claims

    Claim Type Description Sample
    given_name String Required. The user's first name. "given_name": "Jerry"
    family_name String The user's surname. "family_name": "Seldon"
    mobilephone String The user's mobile phone number. "mobilephone": "+61477289117"
    email String Required. Email address. Required for notifications. "email": "jseldon@gmail.com"
    exp Number Required. JWT Expiration Time. UTC timestamp - seconds since UnixEpoch (UTC 1970-01-01T0:0:0Z) - after which the JWT cannot be accepted. "exp": 1475552704
    sub String Required. Subject of the JWT. Locally unique id of the app user in the context of the issuer. "sub": "1234567890"
    iss String Required. The id for the Rundl identity provider registered in step 1. Identifies the principal that issued the JWT. "iss": "1234567890"
    iat Number Required. UTC timestamp - seconds since UnixEpoch (UTC 1970-01-01T0:0:0Z) - when JWT issued. This can determine the age of the JWT. "iat": 1475549104
    aud String Required. Audience (JWT target). Identifies the intended recipients of the JWT. Always "https://go.rundl.com/api/oauth/access_tokens" for getting OAuth access tokens. "aud": "https://go.rundl.com/api/oauth/access_tokens"

    Step 5: Get access token from Rundl

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

    curl -X POST https://stage-go.rundl.com/api/oauth/access_tokens \
      --header 'Content-Type: application/json' \
      --header 'Authorization: JWT <jwt> \
      --data '
        {
          "grant_type":"jwt_bearer",
          "client_id":"1234",
          "scope":"private",
          "stay_signed_in":"true"
        }
      '
    

    Your service will authenticate to Rundl by requesting a user access token, passing the JWT in the Authorization header.

    Step 6: 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 <base64 encoded user access token>

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

    You can also pass the access token as a URL parameter to one of our responsive shared pages.

    https://go.rundl.com/auth/session?access_token={<User-Access-Token>}&redirect_url={redirect_url}

    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

    Take control of acquiring new customers and starting 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.
    service integer Unique identifier for the service being ordered.
    subject string Summary of the order.
    detail string Details about the order, such as a message or description.
    sender object Sender of the order as a participant_lead object.
    participant_leads list List of participant_lead objects
    files list List of Rundl file identifiers. Stage files on auth user's account via the files API prior to sending the order.
    status integer Status of the order. See approval states reference.
    referral_fee string Referral fee currency amount payable to the sender.
    referral_fee_currency string Three-letter ISO currency code. Currently only AUD supported.
    source object Information about the source of the order.
    rundl object Information about the rundl to create when accepting an order.
    request_id integer The unique identifier of the related request. Currently orders are coupled with requests. This will soon be deprecated and orders will stand alone.
    metadata object Context information related to the order
    version integer

    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":23225632,
            "subject":"123 Baker St Caulfield (Demo)",
            "detail":"Sale of property at 123 Baker St Caulfield Vic 3126 ",
            "sender":{
              "context":873900,
              "roles":["Seller"],
              "person":{"id":873900}
            },
            "participant_leads":[
              {
                "person":{
                  "first_name":"Rod",
                  "surname":"Montford",
                  "email":"rmontford@gmail.com",
                  "mobile":"+61412356789"
                },
                "roles":["Seller"]
              }
            ]
          }
        }
      '
    

    The above command returns JSON structured like this:

    {
      "detail":"Sale of property at 123 Baker St Caulfield Vic 3126 ",
      "files":null,
      "id":23226946,
      "metadata":{
        "created_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":873900,
          "name":"Zoe Montford",
          "parent":null,
          "profile_icon_url":null,
          "video_id":null
        },
        "created_date":"\/Date(1513314441677+0000)\/",
        "created_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":873900,
          "name":"Zoe Montford",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/e7392fe26191f428e9a8e8f7d9aee55c",
          "video_id":null
        },
        "id":23226946,
        "updated_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":873900,
          "name":"Zoe Montford",
          "parent":null,
          "profile_icon_url":null,
          "video_id":null
        },
        "updated_date":"\/Date(1513314441677+0000)\/",
        "updated_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":873900,
          "name":"Zoe Montford",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/e7392fe26191f428e9a8e8f7d9aee55c",
          "video_id":null
        }
      },
      "participant_leads":[
        {
          "context":null,
          "id":23226951,
          "person":{
            "email":"rmontford@gmail.com",
            "first_name":"Rod",
            "id":null,
            "mobile":"+61 412 356 789",
            "surname":"Montford"
          },
          "roles":[
            "Seller"
          ],
          "subscribe":null
        }
      ],
      "referral_fee":null,
      "referral_fee_currency":"AUD",
      "request_id":23226952,
      "rundl":null,
      "sender":{
        "context":873900,
        "id":23226950,
        "person":{
          "email":null,
          "first_name":null,
          "id":873900,
          "mobile":null,
          "surname":null
        },
        "roles":[
          "Seller"
        ],
        "subscribe":null
      },
      "service":23225632,
      "source":null,
      "status":0,
      "subject":"123 Baker St Caulfield (Demo)",
      "version":1
    }
    

    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.

    HTTP Request

    POST /orders?account={account_id}

    Query parameters

    Parameter Description
    account_id The id of the selected account when ordering the service

    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.

    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.
    upload_token string Server allocated token identifying the upload session.

    Create an upload_session

    curl -X POST https://stage-go.rundl.com/api/files/upload_sessions?account=123456 \
      --header 'Content-Type: application/json' \
      --header 'Authorization: OAuth <User-Access-Token>' \
      --data '
        {
          "fileUploadSession": {
            "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,
      "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/upload_sessions?account={account_id}

    Query parameters

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

    Update an upload_session

    curl -X PUT https://stage-go.rundl.com/api/files/upload_sessions/d419b96c-b320-4088-b66a-7b7706cfdc57?account=123456 \
      --header 'Content-Type: application/json' \
      --header 'Authorization: OAuth <User-Access-Token>' \
      --data '
        {
          "fileUploadSession": {
            "aws_access_key":"ASIAJAY...WXXTCA",
            "aws_bucket":"uploadsdevrundlco",
            "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",
            "publish":false,
            "size":15992,
            "upload_token":"d419b96c-x111-1111-x11y-7b7706cfdc57",
          }
        }
      '
    

    HTTP Request

    PUT /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 is required before making a purchase, such as when starting a rundl or consuming an add-on. 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.
    host string The host of the rundl. Gid if start, or entity when get.
    files list List of Rundl file identifiers. Stage files on auth user's account via the files API prior to sending the order.
    participant_leads list List of participant_lead objects
    related_rundls list List of related rundls
    fields list List of fields
    service integer Unique identifier of the type of service for the rundl.
    service_name string The name of the service
    brand_color string Hexadecimal colour value. If not set on the rundl, inherits from the service.
    header_image_url string Url for header image. If not set on the rundl, inherits from the service.
    metadata object Context information related to the order
    state integer Status of the order. See states reference.
    state_metadata object Status of the order. See approval states reference.
    last_actioned_step object
    last_actioned_step_state object
    last_actioned_step_state_metadata object
    percentage_complete integer

    Start a rundl

    curl -X POST https://stage-go.rundl.com/api/services/24415244/rundls?account=123456&checkout=30798521&payment_account=30736909 \ 
      --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
            },
            "participant_leads":[
              {
                "context":1688402,
                "roles":[
                  "Real Estate Agent"
                ]
              }
            ],
            "files":[
              24415295
            ]
          }
        }
      '
    

    The above command returns JSON structured like this:

    {
      "actions":null,
      "id":24415298,
      "object":"rundl",
      "add_ons":[
    
      ],
      "brand_color":"#53c876",
      "description":"Sale of property at 123 Baker St Caulfield Vic 3126",
      "header_image_url":null,
      "host":{
        "account_id":1687398,
        "content_image_url":null,
        "description":null,
        "global_type":42,
        "id":2237816,
        "name":"Property Sales",
        "parent":{
          "account_id":1687398,
          "content_image_url":null,
          "description":null,
          "global_type":36,
          "id":1687390,
          "name":"Property Agents (Demo)",
          "parent":null,
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
        "video_id":null
      },
      "last_actioned_step":{
        "account_id":null,
        "content_image_url":null,
        "description":"Thank you for appointing us to be your selling agents.\u000a\u000aWe look forward to achieving a great sale result for you!\u000aIf you haven't already signed the agreements please download and sign them then upload them using the blue pencil below right.",
        "global_type":39,
        "id":24415316,
        "name":"Agency and marketing agreement",
        "parent":null,
        "profile_icon_url":null,
        "video_id":null
      },
      "last_actioned_step_state":{
        "EffectiveDate":"\/Date(1518004197881+1100)\/",
        "Id":0,
        "PreviousState":null,
        "State":1
      },
      "last_actioned_step_state_metadata":{
        "created_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":42,
          "id":2237816,
          "name":"Property Sales",
          "parent":{
            "account_id":null,
            "content_image_url":null,
            "description":null,
            "global_type":36,
            "id":1687390,
            "name":"Property Agents (Demo)",
            "parent":null,
            "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
            "video_id":null
          },
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "created_date":"\/Date(1518004197736+1100)\/",
        "created_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":1688398,
          "name":"Tyson Trennery",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/1199a56934177446b51650a29a24dd3a",
          "video_id":null
        },
        "id":24415317,
        "updated_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":42,
          "id":2237816,
          "name":"Property Sales",
          "parent":{
            "account_id":null,
            "content_image_url":null,
            "description":null,
            "global_type":36,
            "id":1687390,
            "name":"Property Agents (Demo)",
            "parent":null,
            "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
            "video_id":null
          },
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "updated_date":"\/Date(1518004198072+1100)\/",
        "updated_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":1688398,
          "name":"Tyson Trennery",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/1199a56934177446b51650a29a24dd3a",
          "video_id":null
        }
      },
      "metadata":{
        "created_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":42,
          "id":2237816,
          "name":"Property Sales",
          "parent":{
            "account_id":null,
            "content_image_url":null,
            "description":null,
            "global_type":36,
            "id":1687390,
            "name":"Property Agents (Demo)",
            "parent":null,
            "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
            "video_id":null
          },
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "created_date":"\/Date(1518004197000+1100)\/",
        "created_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":1688398,
          "name":"Tyson Trennery",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/1199a56934177446b51650a29a24dd3a",
          "video_id":null
        },
        "id":24415298,
        "updated_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":42,
          "id":2237816,
          "name":"Property Sales",
          "parent":{
            "account_id":null,
            "content_image_url":null,
            "description":null,
            "global_type":36,
            "id":1687390,
            "name":"Property Agents (Demo)",
            "parent":null,
            "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
            "video_id":null
          },
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "updated_date":"\/Date(1518004197000+1100)\/",
        "updated_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":1688398,
          "name":"Tyson Trennery",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/1199a56934177446b51650a29a24dd3a",
          "video_id":null
        }
      },
      "name":"Sale of property at 123 Baker St Caulfield Vic 3126",
      "percentage_complete":0,
      "related_rundls":[
    
      ],
      "service":24415244,
      "service_name":"Real estate sale journey (Demo)",
      "state":{
        "EffectiveDate":"\/Date(1518004197881+1100)\/",
        "Id":0,
        "PreviousState":null,
        "State":2
      },
      "state_metadata":{
        "created_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":42,
          "id":2237816,
          "name":"Property Sales",
          "parent":{
            "account_id":null,
            "content_image_url":null,
            "description":null,
            "global_type":36,
            "id":1687390,
            "name":"Property Agents (Demo)",
            "parent":null,
            "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
            "video_id":null
          },
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "created_date":"\/Date(1518004197350+1100)\/",
        "created_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":1688398,
          "name":"Tyson Trennery",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/1199a56934177446b51650a29a24dd3a",
          "video_id":null
        },
        "id":24415299,
        "updated_context":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":42,
          "id":2237816,
          "name":"Property Sales",
          "parent":{
            "account_id":null,
            "content_image_url":null,
            "description":null,
            "global_type":36,
            "id":1687390,
            "name":"Property Agents (Demo)",
            "parent":null,
            "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
            "video_id":null
          },
          "profile_icon_url":"https:\/\/dev-media.rundl.co\/1687390\/24415219.png",
          "video_id":null
        },
        "updated_date":"\/Date(1518004198159+1100)\/",
        "updated_user":{
          "account_id":null,
          "content_image_url":null,
          "description":null,
          "global_type":43,
          "id":1688398,
          "name":"Tyson Trennery",
          "parent":null,
          "profile_icon_url":"https:\/\/secure.gravatar.com\/avatar\/1199a56934177446b51650a29a24dd3a",
          "video_id":null
        }
      },
      "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}&checkout={checkout}&payment_account={payment_account}

    Query parameters

    Parameter Description
    account_id The id of the selected account when starting the rundl
    checkout The id of a checkout resource created for the purpose of the start rundl request
    payment_account The id of the payment account for the rundl host. The host will be charged the relevant host fee.

    Path parameters

    Parameter Description
    service_id The id of the service being started

    Request body

    See example request.

    Rundl participants

    Overview

    Participants are the stakeholders in the business transaction that's getting delivered as a rundl. People, groups, or members and teams within groups, can participate in rundls.

    The rundl participants API supports adding existing contexts or inviting new users as participants in a rundl.

    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 contexts for that group. Note: Upon adding an existing context, a context's settings determines if a full participant is added, or if a pending participant is added and a request is created for their approval. Where a request is created, the participant transitions from pending to full after accepting the request.

    For new users, add participants by supplying person details including their email address. A pending user and participant is added and an invitation to join Rundl is sent to the address. Upon accepting the invitation (email receiver clicks link in email and signs up) the pending user and participant transitions to a full.

    The participant object

    Attribute Description
    id The id of the participant.
    rundl The id of the rundl the participant is added to.
    context The id of the existing context being added as a participant.
    Expandable
    status Status of the participant.
    roles Array of role names asigned to the participant.
    is_host Flag to indicate if participant is the host.
    observer Flag for making participant an observer.
    created_date The date the participant was added.
    person An object with first_name, last_name, mobile, and email details for a new user to add as a participant.
    message Message included in invitation email when adding a participant.

    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":123456,
              "message":"I would like to add you as a participant in this rundl.",
              "observer":false,
              "context":1688908,
              "person":{}
            }
          }
      '
    

    The above command returns JSON structured like this:

    {
      "context":1688908,
      "created_date":"\/Date(1520237422810+0000)\/",
      "id":25577359,
      "is_host":false,
      "observer":false,
      "person":null,
      "roles":["Default"],
      "rundl":123456,
      "status":2,
      "message":null
    }
    

    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

    curl -X PUT 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":{
              "message":null,
              "context":1688908,
              "created_date":"/Date(1520237422810+0000)/",
              "id":25577359,
              "is_host":false,
              "observer":false,
              "person":null,
              "roles":["Seller"],
              "rundl":123456,
              "status":2
            }
          }
      '
    

    The above command returns JSON structured like this:

    {
      "context":1688908,
      "created_date":"\/Date(1520237422810+0000)\/",
      "id":25577359,
      "is_host":false,
      "observer":false,
      "person":null,
      "roles":["Seller"],
      "rundl":123456,
      "status":2,
      "message":null
    }
    

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

    HTTP Request

    PUT /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.