NAV
examples

Introduction

Welcome

Welcome to the Formbay Developers guide.

This guide will walk you through directly communicating with Formbay and how to integrate Formbay with your own systems. This guides presumes as basic level of understanding of what Formbay can do as well as a familliarity with HTTP requests.

Rest Api Basics

Formbay works on the basics of a REST api. Everything that happens in Formbay is done by sending a HTTP request to Formbay’s backend. This means that everything that the phone and web apps are able to do you will be able to do by constructing the correct HTTP message.

Rather than having to remember and maintain the specific URLs to send messages to, Formbay works by sending links it’s responses. For example, when you first send a message to formbay.com/entrypoint, in its response will include link relations for clients, form_instances, etc… Using the URLs in those link relations will allow you to retrieve information (and further link relations) and submit your own information. It is recommended that if you are developing software which communicates with Formbay you navigate through these link relations rather than hardcoding them, because links are subject to change.

The bulk of this developer’s guide will be detailing the specifics of which information can be retrieved and sent to each resources. Each link relation supports specific media_types or different HTTP request types. For each HTTP request you will need to include the correct media_type. Everytime you submit information the body of your message will need to conform to the specifics of that media_type.

Testing Environment

Formbay has a testing environment where you can create and send forms to see if your system is using Formbay correctly. Like the actual Formbay system you can send forms to anyone, however all data is cleared from the test system every 24 hours.

Include details about how to access test system here after #510 is completed

Formbay Objects

The Formbay system can be understood in terms of its objects and how they relate to one another.

Client

This is an object representing a company or entity on Formbay. A Client will have users, administrators, groups, forms, billing information, invoices, etc.

Form (abstract)

A Form represents a real-world paper document that has been uploaded into the formbay system.

Form Template

A Form Template encapsulates the design of a Form. This includes the placement and definition of fields on the form, roles to be assigned, field sections. It is a template from which a Form Instance may be created.

There can be many Form Templates for a given Form. These may be though of as different “versions” of the forms design.

Form Instance

Form Instances are implementations of a given Form Template. These are the digital equivalent of the filled-out paper form.

This is where the actual submitted field values kept. These will refer back to the field definitions in the associated Form Template by field_id.

Assignment

An Assignment associates an Identity with a Form Instance role. When creating a Form Instance there will need to be an Assignment for each role in the associated Form Template.

Formset (abstract)

A Formset represents an abstract collection of Forms. The forms are usually related to each other and will have Form Instances created together.

Formset Template

A Formset Template groups a specific set of Form Templates together and defines relationships between them.

There can be many Formset Templates for a given Formset. These may be though of as different “versions” of the formset.

Formset Instance

A Formset Instance holds the set of Form Instances created from the Form Templates referred to in the Formset Template. When a Form Instance is created the associated Formset Instance must be specified.

Group

A group is a collection of identities which belongs to a client. This is used to control who has access to which information.

Identity

An Identity represents a person who interacts with the formbay system. They can me members of groups in multiple clients and may be owners of multiple clients.

Source

A Source is a store for data that may be mapped to form fields.

Source Map

A Source Map defines the relationship between Sources and Form Instances.

Plan

A plan defines the payment plans that Formbay offers.

Subscription

A subscription contains information about what plan a client is subscribed to at any point in time.

Charge

The relationship between charges and transactions is slightly complex. A charge is created every month for each client and contains information on how much money the client owes to Formbay. A transaction is created when the total of outstanding charges is greater than the minimum amount that Formbay will charge at once (AUD10 at time of writing). For example, if a client sends AUD1 worth of forms every month and charge will be created for all 10 months but a transaction will only be created on the 10th month.

Transaction

Described in above charge section.

Access Control

Because Formbay can contain sensitive information there are restrictions in place to prevent some people accessing some information. The information that you can access is determined by the groups you belong to.

Walkthrough

Here is a walkthrough of how to retrieve information from a form and how to send a form to someone just by using the HTTP requests to Formbays backend.

Get login credentials

TODO

Need to request toke from Formbay OAuth2 server using given oauth2 client details.

1 Navigate to entrypoint

Accept: ??
Request method: GET

This is the first request you will send whenever you navigate the Formbay. This will response with a redirect to an identity resource corresponding to the identity associated with the given access token.

Response:

https://api.formbay.com.au/identity/22988

2 Follow identity relation

Accept: application/vnd.fb.identity+json; v=2
Request method: GET

This is the second request you will send whenever you interact with Formbay.
The url is the URL that is sent is in the response of the previous request.
You should always start with the entrypoint request because URLs are subject to change.
The response contains details about the user you are logged in with as well as links to other resources that are connected to that user.
Finding any information in formbay is used by navigating links in the response.

identity GET response

{
  "_links": [
    { "href": "/identity/22988/formset", "rel": "formset" },
    { "href": "/identity/22988/formset_instance", "rel": "formset_instances" },
    { "href": "/identity/22988/formset_instance", "rel": "formsets" },
    { "href": "/identity/22988/form_instance", "rel": "instances" },
    { "href": "/identity/22988/group", "rel": "groups" },
    { "href": "/identity", "rel": "identities" },
    { "href": "/identity/22988/assignment", "rel": "assignments" },
    { "href": "/identity/22988/profile_pic", "rel": "profile_pic" },
    { "href": "/identity/22988/contact_verify", "rel": "contact_verification" },
    { "href": "/identity/22988", "rel": "self" },
    { "href": "/client/569", "rel": "client" }
  ],
  "email": "david@formbay.com.au",
  "first_name": "David",
  "last_name": "Clarke",
  "user_id": 22988
}

3 Follow instances relation

Accept: application/vnd.fb.instances+json; v=2
Request method: GET

This resource will display all form_instances belonging to your current user. If you need to access a different form you may need to navigate to a different instances link through connected clients, groups, identities, etc.. As with all navigation all you need to do is follow links in responses with the appropriate media_type. Note, the example response below only contains one form_instance in the example, its possible for it to contain many more.

instances GET response

[
  {
    "_links": [
      { "href": "/form_instance/318499", "rel": "instance" },
      { "href": "/form_instance/318499/assignment", "rel": "assignments" },
      { "href": "/form_instance/318499/document", "rel": "document" },
      { "href": "/form_instance/318499/source_map", "rel": "source_maps" },
      { "href": "/form_instance/318499/page", "rel": "pages" },
      { "href": "/form_instance/318499/file", "rel": "file_submissions" },
      { "href": "/form_instance/318499/remote_sign", "rel": "remote_sign" },
      { "href": "/form/972/version/0", "rel": "template" },
      { "href": "/client/569", "rel": "client" },
      { "href": "/form_instance/318499/originator", "rel": "originator" },
      { "href": "/formset_instance/75727", "rel": "formset_instance" },
      { "href": "/formset_instance/75727", "rel": "formset" }
    ],
    "client_id": 569,
    "closed": false,
    "creation_date": 1467952788,
    "form_id": 972,
    "formset_id": 75727,
    "formset_index": 0,
    "formset_instance_id": 75727,
    "instance_id": 318499,
    "name": "sample.pdf",
    "originator_user_id": 22988,
    "ref_id": null,
    "template_id": 0
  } 
]

4 Follow document relation

Accept: “field_values+json; v=2”
Request method: GET

This resource has an array of field_id and value pairs which show the data entered into the form. It can be somewhat difficult to interpret which field is which without the form_template details, so you made need to retrieve that information from form_template. Because form_templates cannot be modified after an instance is created you can be confident that field_id 8 will always be the same field for all instances belonging to that template.

document GET reponse.

[
  {
    "field_id": 1,
    "value": "field value goes here"
  }
]

Send a form

TODO

Resource guide

access_groups+json

application/vnd.fb.access_groups+json

[  
    {  
        "group_id": 1,  
        "_links": [  
            {  
                "rel": "access",  
                "href": "/formset_instance/20/access/1"  
            }  
        ]  
    },  
    {  
        "group_id": 2,  
        "_links": [  
            {  
                "rel": "access",  
                "href": "/formset_instance/20/access/1"  
            }  
        ]  
    }  
]

This function may be obsolete code from fb1

Only used in GET
Attributes:

access+json

application/vnd.fb.access+json

{
    "group_id": 1
}

Only used in POST Attributes:

assignment+json; v=3

application/vnd.fb.assignment+json; v=3

{
    "assignment_id": 0,
    "instance_id": 5,
    "role_id": 0,
    "user_id": 7128,
    "assignment_date": 1349957430,
    "notification_date": 1349957430,
    "submission_date": 1457925639,
    "contact": "fake@formbay.com.au",
    "message": "installer to submit",
    "_links": [
        {   "rel":"assignment",
            "href":"\/form_instance\/5\/assignment\/0"  },
        {   "rel":"approval",
            "href":"\/form_instance\/5\/assignment\/0\/approval"    },
        {   "rel":"finalisation",
            "href": "\/form_instance\/5\/assignment\/0\/finalisation"   },
        {   "rel":"pages",
            "href":"\/form_instance\/5\/assignment\/0\/page"    },
        {   "rel":"file_submissions",
            "href":"\/form_instance\/5\/assignment\/0\/file"    },
        {   "rel":"template",
            "href":"\/client\/15\/form\/1\/version\/0"    },
        {   "rel":"instance",
            "href":"\/form_instance\/5" },
        {   "rel":"document",
            "href":"\/form_instance\/5\/assignment\/0\/document" },
        {   "rel" : "identity",
            "href": "\/identity\/7128" },
        {   "rel" : "profile_pic",
            "href": "\/identity\/7128\/profile_pic" }
    ]
}

An assignment is a link between a user and a role on a form_instance

Attributes:

*Note: when making a get request the required fields are role_id, instance_id, and user_id or contact.

assignment_patch+json

application/vnd.fb.assignment_patch+json

{
    "due_date": "2015-08-07",
    "message": "This is an example of a message"
}

Used only in PATCH, used to update details of an assignment

Attributes:

assignments+json; v=3

application/vnd.fb.assignments+json; v=3

[
    {
        "role_idx"           : 0,
        "assignment_id"      : 0,
        "instance_id"        : 7,
        "user_id"            : 1234,
        "formset_instance_id": 5,
        "form_id"            : 3,
        "template_id"        : 0,
        "assignment_date"    : 1349957430,
        "notification_date"  : 1349957430,
        "cancellation_date"  : 1349766630,
        "submission_date"    : null,
        "finalise_date"      : null,
        "approval_date"      : null,
        "message"            : "installer to submit",
        "status"             : "cancelled",
        "_links"             : [
            {   "rel": "form_assignment", 
                "href": "/form_instance/7/assignment/0"},
            {   "rel": "assignment", 
                "href": "/form_instance/7/assignment/0"},
            {   "rel": "submission", 
                "href": "/form_instance/7/assignment/0/submission"},
            {   "rel": "assignment_values", 
                "href": "/form_instance/7/assignment/0/values"},
            {   "rel": "approval", 
                "href": "/form_instance/7/assignment/0/approval"},
            {   "rel": "finalisation", 
                "href": "/form_instance/7/assignment/0/finalisation"},
            {   "rel": "assignment_document", 
                "href": "/form_instance/7/assignment/0/document"},
            {   "rel": "pages", 
                "href": "/form_instance/7/assignment/0/page"},
            {   "rel": "file_submissions", 
                "href": "/form_instance/7/assignment/0/file"},
            {   "rel": "template", 
                "href": "/client/15/form/3/version/0"},
            {   "rel": "instance", 
                "href": "/form_instance/7"},
            {   "rel": "document", 
                "href": "/form_instance/7/assignment/0/document"},
            {   "rel": "profile_pic", 
               "href": "/identity/1234/profile_pic"}
        ]
    },
    {
        "role_idx"               : 0,
        "assignment_id"          : 1,
        "instance_id"            : 7,
        "user_id"                : 7128,
        "formset_instance_id"    : 5,
        "form_id"                : 3,
        "template_id"            : 0,
        "assignment_date"        : 1349957430,
        "notification_date"      : 1349957430,
        "submission_date"        : null,
        "finalise_date"          : null,
        "approval_date"          : null,
        "cancellation_date"      : null,
        "first_name"             : "Jas",
        "last_name"              : "Singh",
        "email"                  : "fakep0zjv8:jaz@konceive.com.au",
        "message"                : "installer to submit",
        "status"                 : "notified",
        "_links"                 : [
            {   "rel": "form_assignment", 
                "href": "/form_instance/7/assignment/1"},
            {   "rel": "assignment", 
                "href": "/form_instance/7/assignment/1"},
            {   "rel": "submission", 
                "href": "/form_instance/7/assignment/1/submission"},
            {   "rel": "assignment_values", 
                "href": "/form_instance/7/assignment/1/values"},
            {   "rel": "approval", 
                "href": "/form_instance/7/assignment/1/approval"},
            {   "rel": "finalisation", 
                "href": "/form_instance/7/assignment/1/finalisation"},
            {   "rel": "assignment_document", 
                "href": "/form_instance/7/assignment/1/document"},
            {   "rel": "pages", 
                "href": "/form_instance/7/assignment/1/page"},
            {   "rel": "file_submissions", 
                "href": "/form_instance/7/assignment/1/file"},
            {   "rel": "template", 
                "href": "/client/15/form/3/version/0"},
            {   "rel": "instance", 
                "href": "/form_instance/7"},
            {   "rel": "document", 
                "href": "/form_instance/7/assignment/1/document"},
            {   "rel": "profile_pic", 
                "href": "/identity/7128/profile_pic"},
        ]
    }
]

used when retrieving multiple assignments only used in GET

response is an array of objects with the following attributes:

card_details+json

application/vnd.fb.card_details+json

{
    "stripe_toke": "stripeTokenGoesHere1232"
}

Attributes:

TODO add fields returned when using GET (need to add card to stripe account)

charge+json

application/vnd.fb.charge+json

{
    "client_id": 28,
    "charge_id": 2,
    "transaction_id": 4,
    "invoice_year": 2010,
    "invoice_month": 2,
    "currency": "AUD",
    "amount": 50,
    "tier_limits": [
        { "send_count": 100, "send_cost": 50 },
        { "send_count": 500, "send_cost": 30 },
        { "send_count": 4294967296, "send_cost": 15 }
    ],
    "total_instances": 1,
    "bonus_sends_before": 0,
    "bonus_sends_after": 0,
    "base_subscription_amount": 0,
    "_links": [
        { "rel": "client", "href": "\/client\/28\/" },
        { "rel": "transaction", "href": "\/client\/28\/transaction\/2" }
    ]
}

a charge is the information related to a subscription periods, each month if a client has open charges with total amount owing greater than mimimum charge amount the client’s credit card is charged, a transaction is created and those charges are closed. Only used with GET

Attributes:

charges+json

application/vnd.fb.charges+json

[
    {
        "client_id": 28,
        "charge_id": 4,
        "transaction_id": null,
        "invoice_year": 2011,
        "invoice_month": 3,
        "currency": "AUD",
        "amount": 100,
        "tier_limits": [
            { "send_count": 100, "send_cost": 50 },
            { "send_count": 500, "send_cost": 30 },
            { "send_count": 4294967296, "send_cost": 15 }
        ],
        "total_instances": 2,
        "bonus_sends_before": 0,
        "bonus_sends_after": 0,
        "base_subscription_amount": 0,
        "_links": [
            { "rel": "client", "href": "\/client\/28\/" }
        ]
    },
    {
        "client_id": 28,
        "charge_id": 2,
        "transaction_id": 4,
        "invoice_year": 2010,
        "invoice_month": 2,
        "currency": "AUD",
        "amount": 50,
        "tier_limits": [
            { "send_count": 100, "send_cost": 50 },
            { "send_count": 500, "send_cost": 30 },
            { "send_count": 4294967296, "send_cost": 15 }
        ],
        "total_instances": 1,
        "bonus_sends_before": 0,
        "bonus_sends_after": 0,
        "base_subscription_amount": 0,
        "_links": [
            { "rel": "client", "href": "\/client\/28\/" },
            { "rel": "transaction", "href": "\/client\/28\/transaction\/2" }
        ]
    }
]

Only used in GET

Response is an array of objects, each of which have the the following attributes:

client+json

example

{
    "name":"John Cena",
    "client_id":34,
    "description":"description goes here",
    "email":"email@email.com",
    "phone":"+614555555",
    "color":"9932CC",
    "stripe_customer_id":null,
    "bonus_free_sends":2,
    "admin_group_id":1,
    "_links":[
        {   "rel":"self",
            "href":"\/client\/34" },
        {   "rel":"identities",
            "href":"\/client\/34\/identity" },
        {   "rel":"profiles",
            "href":"\/client\/34\/profile" },
        {   "rel":"profile_types",
            "href":"\/client\/34\/profile_type" },
        {   "rel":"forms",
            "href":"\/client\/34\/form" },
        {   "rel":"templates",
            "href":"\/client\/34\/template" },
        {   "rel":"formset_instances",
            "href":"\/client\/34\/formset_instance" },
        {   "rel":"formsets",
            "href":"\/client\/34\/formset" },
        {   "rel":"formset_templates",
            "href":"\/client\/34\/formset_template" },
        {   "rel":"documents",
            "href":"\/document" },
        {   "rel":"assignments",
            "href":"\/client\/34\/assignment" },
        {   "rel":"sources",
            "href":"\/client\/34\/source" },
        {   "rel":"groups",
            "href":"\/client\/34\/group" },
        {   "rel":"assignments",
            "href":"\/client\/34\/assignment" },
        {   "rel":"instances",
            "href":"\/client\/34\/form_instance" },
        {   "rel":"charges",
            "href":"\/client\/34\/charge" },
        {   "rel":"transactions",
            "href":"\/client\/34\/transaction" },
        {   "rel":"usage",
            "href":"\/client\/34\/usage" },
        {   "rel":"card",
            "href":"\/client\/34\/card" },
        {   "rel":"logo",
            "href":"\/client\/34\/logo_pic" },
        {   "rel":"group",
            "href":"\/client\/34\/group\/1" }
    ]
}

application/vnd.fb.client+json

Description

This is an object representing a company or entity on Formbay. A Client will encapsulate a set of users, administrators, groups, forms, billing information, invoices, etc.

Attributes

client_patch+json

application/vnd.fb.client_patch+json

{
    "color": "FFFFFF",
    "description": "description here",
    "name": "client name here"
}

Only used in patch Used to update a client

Attributes:

clients+json

application/vnd.fb.clients+json

[
    {
        "name":"Company A",
        "client_id":1,
        "description":"abcdefghi",
        "stripe_customer_id":"cus_5oSyeuiOSE4WSO",
        "bonus_free_sends":0,
        "admin_group_id":0,
        "_links":[
            {   "rel":"self",
                "href":"\/client\/1"    },
            {   "rel":"identities",
                "href":"\/client\/1\/identity"  },
            {   "rel":"profiles",
                "href":"\/client\/1\/profile"   },
            {   "rel":"profile_types",
                "href":"\/client\/1\/profile_type"  },
            {   "rel":"forms",
                "href":"\/client\/1\/form"    },
            {   "rel":"templates",
                "href":"\/client\/1\/template"  },
            {   "rel":"formset_instances",
                "href":"\/client\/1\/formset_instance"  },
            {   "rel":"formsets",
                "href":"\/client\/1\/formset"   },
            {   "rel":"formset_templates",
                "href":"\/client\/1\/formset_template"  },
            {   "rel":"documents",
                "href":"\/document"   },
            {   "rel":"assignments",
                "href":"\/client\/1\/assignment"    },
            {   "rel":"sources",
                "href":"\/client\/1\/source"    },  
            {   "rel":"groups",
                "href":"\/client\/1\/group" },
            {   "rel":"assignments",
                "href":"\/client\/1\/assignment"    },
            {   "rel":"instances",
                "href":"\/client\/1\/form_instance" },
            {   "rel":"charges",
                "href":"\/client\/1\/charge"    },
            {   "rel":"transactions",
                "href":"\/client\/1\/transaction"   },
            {   "rel":"usage",
                "href":"\/client\/1\/usage" },
            {   "rel":"card",
                "href":"\/client\/1\/card"  },
            {   "rel":"logo",
                "href":"\/client\/1\/logo_pic"  },
            {   "rel":"group",
                "href":"\/client\/1\/group\/0"  }
        ]
    },
    {   "name":"Company B",
        "client_id":5,
        "description":"",
        "stripe_customer_id":"",
        "bonus_free_sends":0,
        "admin_group_id":0,
        "_links":[
            {   "rel":"self",
                "href":"\/client\/5"    },
            {   "rel":"identities",
                "href":"\/client\/5\/identity"  },
            {   "rel":"profiles",
                "href":"\/client\/5\/profile"   },
            {   "rel":"profile_types",
                "href":"\/client\/5\/profile_type"  },
            {   "rel":"forms",
                "href":"\/client\/5\/form"    },
            {   "rel":"templates",
                "href":"\/client\/5\/template"  },
            {   "rel":"formset_instances",
                "href":"\/client\/5\/formset_instance"  },
            {   "rel":"formsets",
                "href":"\/client\/5\/formset"   },
            {   "rel":"formset_templates",
                "href":"\/client\/5\/formset_template"  },
            {   "rel":"documents",
                "href":"\/document" },
            {   "rel":"assignments",
                "href":"\/client\/5\/assignment"    },
            {   "rel":"sources",
                "href":"\/client\/5\/source"    },
            {   "rel":"groups",
                "href":"\/client\/5\/group" },
            {   "rel":"assignments",
                "href":"\/client\/5\/assignment"    },
            {   "rel":"instances",
                "href":"\/client\/5\/form_instance" },
            {   "rel":"charges",
                "href":"\/client\/5\/charge"    },
            {   "rel":"transactions",
                "href":"\/client\/5\/transaction"   },
            {   "rel":"usage",
                "href":"\/client\/5\/usage" },
            {   "rel":"card",
                "href":"\/client\/5\/card"},
            {   "rel":"logo",
                "href":"\/client\/5\/logo_pic"  },
            {   "rel":"group",
                "href":"\/client\/5\/group\/0"  }
        ]
    }
]

Only used in GET
Response is an array of objects each with the following attributes:

field_values+json; v=2

application/vnd.fb.field_values+json; v=2

{
    "field_id": 1,
    "value": "field value goes here"
}

This structure is used to add values of individual fields to a form instance. It is an array of objects with the properties field_id and value.

Attributes

file_submissions+json

application/vnd.fb.file_submissions+json 

{
    "file_id": 1,
    "instance_id": 23,
    "assignment_id": 4,
    "_links": [
        {   "rel"   :  "assignment",
            "href"  :   "form_instance/3/assignment/4"   },
        {   "rel"   :   "file_submission",
            "href"  :   "form_instance/3/assignment/4/file/fileHashHere" }
    ]
}

A response with the media_type file_submissions will be an array of objects with the following attributes:

form+json; v=2

application/vnd.fb.form+json

POST example

{
    "name": "John Smith",
    "group_id": 1,
    "client_id": 55
}

GET example

{
    "form_id": 12,
    "name": "John Smith",
    "_links": [
        {   "rel": "templates",
            "href": "/client/55/form/12/version"    },
        {   "rel": "self",
            "href": "/client/55/form/12"    },
        {   "rel": "forms",
            "href": "client/55/form"    },
        {   "rel": "instances",
            "href": "/client/55/form/12/instance"   },
        {   "rel": "cover",
            "href": "/form/55/cover"    }
    ]
}

a from in the formbay system, a form can have multiple templates(which are like editions or versions) from which instances can be created.

Attributes:

formset_instance+json; v=2

application/vnd.fb.formset_instance+json; v=2

{
    "formset_instance_id":19499,
    "formset_id":19499,
    "formset_template_id":26,
    "creation_date":1404268272,
    "description":null,
    "name":"STC Installation",
    "_links":[
        {   "rel":"instances",
            "href":"\/identity\/4\/formset_instance\/19499\/instance"   },
        {   "rel":"assignments",
            "href":"\/client\/26\/formset_instance\/19499\/assignment"  },
        {   "rel":"source_maps",
            "href":"\/identity\/4\/formset_instance\/19499\/source_map" },
        {   "rel":"formset_template",
            "href":"\/formset_template\/26" },
        {   "rel":"access_groups",  
            "href":"\/formset_instance\/19499\/access"  },
        {   "rel":"self",
            "href":"\/identity\/4\/formset_instance\/19499" }
    ],
    "ref_id":"T322240"
}

a specific instance of a formset_template

Attributes:

formset_instance_patch+json

application/vnd.fb.formset_instance_patch+json

{
    "description": "some description here",
    "name": "formset name here"
}

Attribute:

Note: This resource is only used for POST

formset_instances+json; v=2

application/vnd.fb.formset_instances+json; v=2

{
    "formset_instance_id":5,
    "formset_id":5,
    "formset_template_id":7,
    "creation_date":1353586501,
    "description":"some description",
    "name":"STC Installation",
    "_links":[
        {   "rel":"instances",
            "href":"\/client\/15\/formset_instance\/5\/instance"    },
        {   "rel":"assignments",
            "href":"\/client\/15\/formset_instance\/5\/assignment"  },
        {   "rel":"source_maps",
            "href":"\/client\/15\/formset_instance\/5\/source_map"  },
        {   "rel":"formset_template",
            "href":"\/formset_template\/7"  },
        {   "rel":"access_groups",
            "href":"\/formset_instance\/5\/access"  },
        {   "rel":"self",
            "href":"\/formset_instance\/5"  }
    ],
    "ref_id":"dan_sul",
    "instances":[
        {
            "_links":[
                {   "rel":"form_assignments",
                    "href":"\/form_instance\/5\/assignment" },
                {   "rel":"assignments",
                    "href":"\/form_instance\/5\/assignment" },
                {   "rel":"remote_sign",
                    "href":"\/form_instance\/5\/remote_sign"    },
                {   "rel":"instance",
                    "href":"\/form_instance\/5" },
                {   "rel":"template",
                    "href":"\/form\/1\/version\/0"  }
            ],
            "form_id":1,
            "instance_id":5,
            "formset_index":0,
            "template_id":0,
            "creation_date":1353586501,
            "last_modified":1360175520,
            "enabled":true,
            "name":"Customer Acknowledgement",
            "status":"new",
            "closed":false,
            "optional":false
        },
        {
            "_links":[
                {   "rel":"form_assignments",
                    "href":"\/form_instance\/6\/assignment" },
                {   "rel":"assignments",
                    "href":"\/form_instance\/6\/assignment" },
                {   "rel":"remote_sign",
                    "href":"\/form_instance\/6\/remote_sign"    },
                {   "rel":"instance",
                    "href":"\/form_instance\/6" },
                {   "rel":"template",
                    "href":"\/form\/2\/version\/0"  }
            ],
            "form_id":2,
            "instance_id":6,
            "formset_index":1,
            "template_id":0,
            "creation_date":1353586501,
            "last_modified":1394028286,
            "enabled":true,
            "name":"Grid Connect",
            "status":"new",
            "closed":false,
            "optional":false
        }
    ]
}

only used with GET and HEAD response is an array of objects with the following attributes:application/vnd.fb.formset_instance+json

a specific instance of a formset_template

Attributes:

formset+json;

application/vnd.fb.formset+json;

{
    "name": "formset name goes here"
}

Attributes:

formsets+json;

application/vnd.fb.formset+json; 

[
  {
    "_links": [
      {
        "href": "/client/44",
        "rel": "client"
      },
      {
        "href": "/client/44/formset/2/formset_template",
        "rel": "formset_templates"
      },
      {
        "href": "/client/44/formset/2/formset_instance",
        "rel": "formset_instances"
      },
      {
        "href": "/client/44/formset/2/cover",
        "rel": "cover"
      },
      {
        "href": "/client/44/formset/2",
        "rel": "self"
      }
    ],
    "client_id": 44,
    "formset_id": 2,
    "name": "test formset abcd"
  }
]

Get response is an array of objects, each with the following attributes:

formset_patch+json

application/vnd.fb.formset_patch+json

{
    "formset_id": 12,
    "name": "new formset name here"
}

Attributes:

formset_template+json

application/vnd.fb.formset_template+json

PUT example

{
    "formset_id":2,
    "formset_template_id":82,
    "creation_date":1402455613,
    "client_id":26,
    "name":"test formset abcd",
    "forms":[
        {   "form_id":83,
            "template_id":0 },
        {   "form_id":84,
            "template_id":0 },
        {   "form_id":86,
            "template_id":0 },
        {   "form_id":55,
            "template_id":1 }
    ],
    "description_script":"$0_5"
}

GET example

{
    "formset_id":2,
    "formset_template_id":82,
    "creation_date":1402455613,
    "client_id":26,
    "name":"test formset abcd",
    "forms":[
        {   "form_id":83,
            "template_id":0,
            "_links":[
                {   "rel":"template",
                    "href":"\/client\/26\/form\/83\/version\/0" },
                {   "rel":"cover",
                    "href":"\/form\/83\/cover"}
            ]
        },
        {   "form_id":84,
            "template_id":0,
            "_links":[
                {   "rel":"template",
                    "href":"\/client\/26\/form\/84\/version\/0" },
                {   "rel":"cover",
                    "href":"\/form\/84\/cover"  }
            ]
        },
        {   "form_id":86,
            "template_id":0,
            "_links":[
                {   "rel":"template",
                    "href":"\/client\/26\/form\/86\/version\/0" },
                {   "rel":"cover",
                    "href":"\/form\/86\/cover"}
            ]
        },
        {   "form_id":55,
            "template_id":1,
            "_links":[
                {   "rel":"template",
                    "href":"\/client\/26\/form\/55\/version\/1"},
                {   "rel":"cover",
                    "href":"\/form\/55\/cover"}
            ]
        }
    ],
    "description_script":"$0_5",
    "_links":[
        {   "rel":"self",
            "href":"\/formset_template\/82" },
        {   "rel":"publish",
            "href":"\/formset_template\/82\/publish"    },
        {   "rel":"formset_instances",
            "href":"\/client\/26\/formset_template\/82\/formset_instance"   },
        {   "rel":"formsets",
            "href":"\/client\/26\/formset_template\/82\/formset_instance"}
    ]
}

a template of a formset from which formset_instances can be created from

Attributes:

formset_templates+json

application/vnd.fb.formset_templates+json

[
    {
        "formset_id":2,
        "formset_template_id":7,
        "creation_date":1359950271,
        "client_id":26,
        "name":"test formset abcd",
        "_links": [
            {   "rel":"self",
                "href":"\/formset_template\/7"  },
            {   "rel":"publish",
                "href":"\/formset_template\/7\/publish" },
            {   "rel":"formset_instances",
                "href":"\/client\/26\/formset_template\/7\/formset_instance" },
            {   "rel":"formsets",   
                "href":"\/client\/26\/formset_template\/7\/formset_instance"}
        ] 
    },
    {   
        "formset_id":2,
        "formset_template_id":26,
        "creation_date":1402455613,
        "client_id":26,
        "published":1402455613,
        "name":"test formset abcd",
        "_links": [
            {   "rel":"self",
                "href":"\/formset_template\/26" },
            {   "rel":"publish",
                "href":"\/formset_template\/26\/publish" },
            {   "rel":"formset_instances",
                "href":"\/client\/26\/formset_template\/26\/formset_instance" },
            {   "rel":"formsets",
                "href":"\/client\/26\/formset_template\/26\/formset_instance" }
        ]
    },
    {
        "formset_id":2,
        "formset_template_id":82,
        "creation_date":1402455613,
        "client_id":26,
        "name":"test formset abcd",
        "_links": [
            {   "rel":"self",
                "href":"\/formset_template\/82" },
            {   "rel":"publish",
                "href":"\/formset_template\/82\/publish" },
            {   "rel":"formset_instances",
                "href":"\/client\/26\/formset_template\/82\/formset_instance" },
            {   "rel":"formsets",
                "href":"\/client\/26\/formset_template\/82\/formset_instance" }
        ]
    },
    {
        "formset_id":476,
        "formset_template_id":476,
        "creation_date":1402455613,
        "client_id":26,
        "name":"My Special Formset",
        "_links": [
            {   "rel":"self",
                "href":"\/formset_template\/476" },
            {   "rel":"publish",
                "href":"\/formset_template\/476\/publish" },
            {   "rel":"formset_instances",
                "href":"\/client\/26\/formset_template\/476\/formset_instance" },
            {   "rel":"formsets",
                "href":"\/client\/26\/formset_template\/476\/formset_instance" }
        ]
    }
]

only used with GET response is an array of objects each with the following attributes:

forms+json

application/vnd.fb.forms+json

[
    {
        "_links":[
            {   "rel":"templates",
                "href":"\/client\/15\/form\/1\/version" },
            {   "rel":"self",
                "href":"\/client\/15\/form\/1"  },
            {   "rel":"forms",
                "href":"\/client\/15\/form" },
            {   "rel":"instances",
                "href":"\/client\/15\/form\/1\/instance"    },
            {   "rel":"cover",
                "href":"\/form\/1\/cover"   },
            {   "rel":"template",
                "href":"\/client\/15\/form\/1\/version\/1"  }
        ],
        "form_id":1,
        "name":"Customer Acknowledgement"
    },
    {
        "_links":[
            {   "rel":"templates",
                "href":"\/client\/15\/form\/2\/version" },
            {   "rel":"self",
                "href":"\/client\/15\/form\/2"  },
            {   "rel":"forms",
                "href":"\/client\/15\/form"   },
            {   "rel":"instances",
                "href":"\/client\/15\/form\/2\/instance"    },
            {   "rel":"cover",
                "href":"\/form\/2\/cover"   },
            {   "rel":"template",
                "href":"\/client\/15\/form\/2\/version\/5"  }
        ],
        "form_id":2,
        "name":"Grid Connect"
    },
    {   
        "_links":[
            {   "rel":"templates",
                "href":"\/client\/15\/form\/3\/version" },
            {   "rel":"self",
                "href":"\/client\/15\/form\/3"  },
            {   "rel":"forms",
                "href":"\/client\/15\/form" },
            {   "rel":"instances",
                "href":"\/client\/15\/form\/3\/instance"    },
            {   "rel":"cover",
                "href":"\/form\/3\/cover"   },
            {   "rel":"template",
                "href":"\/client\/15\/form\/3\/version\/3"  }
        ],
        "form_id":3,
        "name":"Electrical Work Request"
    }
]

only used with GET response is an array of objects, each with the following attributes:

group+json

application/vnd.fb.group+json

{
    "group_id":4377,
    "client_id":189,
    "name":"numberwang",
    "creation_timestamp":1471574748,
    "_links":[
        {   "rel":"client",
            "href":"\/client\/189"  },
        {   "rel":"formset_instances",
            "href":"\/client\/189\/group\/4377\/formset_instance"   },
        {   "rel":"assignments",
            "href":"\/client\/189\/group\/4377\/assignment" },
        {   "rel":"instances",
            "href":"\/client\/189\/group\/4377\/instance"   },
        {   "rel":"group",
            "href":"\/client\/189\/group\/4377" },
        {   "rel":"members",
            "href":"\/client\/189\/group\/4377\/member" },
        {   "rel":"profiles",
            "href":"\/client\/189\/group\/4377\/profile"    },
        {   "rel":"templates",
            "href":"\/client\/189\/group\/4377\/template"   },
        {   "rel":"forms",
            "href":"\/client\/189\/group\/4377\/form"   },
        {   "rel":"formsets",
            "href":"\/client\/189\/group\/4377\/formset"    }
    ]
}

Description

A client group. Access to objects can be controlled on a per group basis.

Objects that a group can own include:

Attributes

groups+json

application/vnd.fb.groups+json

[
    {   
        "group_id":66,
        "client_id":119,
        "name":"Solar Sun",
        "creation_timestamp":1389309851,
        "_links":[
            {   "rel":"client",
                "href":"\/client\/119"  },
            {   "rel":"formset_instances",
                "href":"\/client\/119\/group\/66\/formset_instance" },
            {   "rel":"assignments",
                "href":"\/client\/119\/group\/66\/assignment"   },
            {   "rel":"instances",
                "href":"\/client\/119\/group\/66\/instance" },
            {   "rel":"group",
                "href":"\/client\/119\/group\/66"   },
            {   "rel":"members",
                "href":"\/client\/119\/group\/66\/member"   },
            {   "rel":"profiles",
                "href":"\/client\/119\/group\/66\/profile"  },
            {   "rel":"templates",
                "href":"\/client\/119\/group\/66\/template" },
            {   "rel":"forms",
                "href":"\/client\/119\/group\/66\/form" },
            {   "rel":"formsets",
                "href":"\/client\/119\/group\/66\/formset"}
        ]
    },
    {
        "group_id":4376,
        "client_id":119,
        "name":"Another group here",
        "creation_timestamp":1297473490,
        "_links":[
            {   "rel":"client",
                "href":"\/client\/119"  },
            {   "rel":"formset_instances",
                "href":"\/client\/119\/group\/4376\/formset_instance"   },
            {   "rel":"assignments",
                "href":"\/client\/119\/group\/4376\/assignment" },
            {   "rel":"instances",
                "href":"\/client\/119\/group\/4376\/instance"   },
            {   "rel":"group",  
                "href":"\/client\/119\/group\/4376" },
            {   "rel":"members",
                "href":"\/client\/119\/group\/4376\/member" },
            {   "rel":"profiles",
                "href":"\/client\/119\/group\/4376\/profile"    },
            {   "rel":"templates",
                "href":"\/client\/119\/group\/4376\/template"   },
            {   "rel":"forms",
                "href":"\/client\/119\/group\/4376\/form"   },
            {   "rel":"formsets",
                "href":"\/client\/119\/group\/4376\/formset"    }
        ]
    }
]

only used in GET response is an array of objects with the following attributes:

identities+json

application/vnd.fb.identities+json

[
  {
    "_links": [
      {
        "href": "/identity/6/formset",
        "rel": "formset"
      },
      {
        "href": "/identity/6/formset_instance",
        "rel": "formset_instances"
      },
      {
        "href": "/identity/6/formset_instance",
        "rel": "formsets"
      },
      {
        "href": "/identity/6/form_instance",
        "rel": "instances"
      },
      {
        "href": "/identity/6/group",
        "rel": "groups"
      },
      {
        "href": "/identity",
        "rel": "identities"
      },
      {
        "href": "/identity/6/assignment",
        "rel": "assignments"
      },
      {
        "href": "/identity/6/profile_pic",
        "rel": "profile_pic"
      },
      {
        "href": "/identity/6/contact_verify",
        "rel": "contact_verification"
      },
      {
        "href": "/identity/6",
        "rel": "self"
      }
    ],
    "email": "primesps@yahoo.com",
    "first_name": "Mark",
    "last_name": "Last",
    "phone": "555666777:fakeu34y2rfihfb",
    "user_id": 6
  },
  {
    "_links": [
      {
        "href": "/identity/11/formset",
        "rel": "formset"
      },
      {
        "href": "/identity/11/formset_instance",
        "rel": "formset_instances"
      },
      {
        "href": "/identity/11/formset_instance",
        "rel": "formsets"
      },
      {
        "href": "/identity/11/form_instance",
        "rel": "instances"
      },
      {
        "href": "/identity/11/group",
        "rel": "groups"
      },
      {
        "href": "/identity",
        "rel": "identities"
      },
      {
        "href": "/identity/11/assignment",
        "rel": "assignments"
      },
      {
        "href": "/identity/11/profile_pic",
        "rel": "profile_pic"
      },
      {
        "href": "/identity/11/contact_verify",
        "rel": "contact_verification"
      },
      {
        "href": "/identity/11",
        "rel": "self"
      }
    ],
    "email": "info@gotjsolar.com",
    "first_name": "primesps",
    "last_name": "yahoo",
    "phone": "+61422222222",
    "user_id": 11
  }
]

Only used with GET response is an array of objects, each with the following attributes:

identity+json; v=2

application/vnd.fb.identity+json; v=2

PUT example

{
    "first_name": "John",
    "phone": "+333444555"
}

GET example

{
  "_links": [
    {
      "href": "/identity/6/formset",
      "rel": "formset"
    },
    {
      "href": "/identity/6/formset_instance",
      "rel": "formset_instances"
    },
    {
      "href": "/identity/6/formset_instance",
      "rel": "formsets"
    },
    {
      "href": "/identity/6/form_instance",
      "rel": "instances"
    },
    {
      "href": "/identity/6/group",
      "rel": "groups"
    },
    {
      "href": "/identity",
      "rel": "identities"
    },
    {
      "href": "/identity/6/assignment",
      "rel": "assignments"
    },
    {
      "href": "/identity/6/profile_pic",
      "rel": "profile_pic"
    },
    {
      "href": "/identity/6/contact_verify",
      "rel": "contact_verification"
    },
    {
      "href": "/identity/6",
      "rel": "self"
    }
  ],
  "email": "primesps@yahoo.com",
  "first_name": "first",
  "phone": "555666777",
  "user_id": 6,
  "username": "primesp"
}

an identity represent a user of formbay, an identity can be assigned to a form_instance or a formset_instance, or be added to a group of a client

Attributes:

identity_patch+json

application/vnd.fb.identity_patch+json

{
    "first_name": "John",
    "last_name": "Smith"
}

This resource is used to update an identity. Only used with PATCH

Attributes:

instance+json

application/vnd.fb.instance+json

{
  "_links": [
    {
      "href": "/form_instance/59288",
      "rel": "instance"
    },
    {
      "href": "/form_instance/59288/assignment",
      "rel": "assignments"
    },
    {
      "href": "/form_instance/59288/document",
      "rel": "document"
    },
    {
      "href": "/form_instance/59288/source_map",
      "rel": "source_maps"
    },
    {
      "href": "/form_instance/59288/remote_sign",
      "rel": "remote_sign"
    },
    {
      "href": "/form_instance/59288/page",
      "rel": "pages"
    },
    {
      "href": "/form_instance/59288/file",
      "rel": "file_submissions"
    },
    {
      "href": "/client/26/form/3/version/3",
      "rel": "template"
    },
    {
      "href": "/form_instance/59288/originator",
      "rel": "originator"
    },
    {
      "href": "/formset_instance/19607",
      "rel": "formset_instance"
    },
    {
      "href": "/formset_instance/19607",
      "rel": "formset"
    }
  ],
  "assigned": null,
  "charge_id": null,
  "client_id": 26,
  "closed": true,
  "creation_date": 1404356543,
  "form_id": 3,
  "formset_id": 19607,
  "formset_index": 2,
  "formset_instance_id": 19607,
  "instance_id": 59288,
  "name": "Electrical Work Request",
  "optional": false,
  "originator_user_id": "1",
  "ref_id": "206243",
  "source_map": [
    {
      "_links": [
        {
          "href": "/client/26/source/4",
          "rel": "source"
        },
        {
          "href": "/client/26/source/4/data/19067",
          "rel": "source_record"
        },
        {
          "href": "/form_instance/59288/source_map/2",
          "rel": "source_map"
        }
      ],
      "record_id": 19067,
      "source_id": 2,
      "type_id": 4
    }
  ],
  "status": "new",
  "template_id": 3,
  "user_id": 0
}

In formbay, ‘instance’ refers to a specific instance of a form which is assigned to one or more person(s). And instance is creating by putting data into a template.

An instance cannot own any other objects

Attributes:

Fields with an asterix (*) are required.

instances+json; v=2

application/vnd.fb.instances+json; v=2

[
  {
    "_links": [
      {
        "href": "/form_instance/59027",
        "rel": "instance"
      },
      {
        "href": "/form_instance/59027/assignment",
        "rel": "assignments"
      },
      {
        "href": "/form_instance/59027/document",
        "rel": "document"
      },
      {
        "href": "/form_instance/59027/source_map",
        "rel": "source_maps"
      },
      {
        "href": "/form_instance/59027/page",
        "rel": "pages"
      },
      {
        "href": "/form_instance/59027/file",
        "rel": "file_submissions"
      },
      {
        "href": "/form_instance/59027/remote_sign",
        "rel": "remote_sign"
      },
      {
        "href": "/form/2/version/3",
        "rel": "template"
      },
      {
        "href": "/client/26",
        "rel": "client"
      },
      {
        "href": "/form_instance/59027/originator",
        "rel": "originator"
      },
      {
        "href": "/formset_instance/19520",
        "rel": "formset_instance"
      },
      {
        "href": "/formset_instance/19520",
        "rel": "formset"
      }
    ],
    "client_id": 26,
    "closed": false,
    "creation_date": 1404273179,
    "form_id": 2,
    "formset_id": 19520,
    "formset_index": 1,
    "formset_instance_id": 19520,
    "instance_id": 59027,
    "name": "Grid Connect",
    "originator_user_id": 1,
    "ref_id": "206069",
    "template_id": 3
  },
  {
    "_links": [
      {
        "href": "/form_instance/59028",
        "rel": "instance"
      },
      {
        "href": "/form_instance/59028/assignment",
        "rel": "assignments"
      },
      {
        "href": "/form_instance/59028/document",
        "rel": "document"
      },
      {
        "href": "/form_instance/59028/source_map",
        "rel": "source_maps"
      },
      {
        "href": "/form_instance/59028/page",
        "rel": "pages"
      },
      {
        "href": "/form_instance/59028/file",
        "rel": "file_submissions"
      },
      {
        "href": "/form_instance/59028/remote_sign",
        "rel": "remote_sign"
      },
      {
        "href": "/form/3/version/3",
        "rel": "template"
      },
      {
        "href": "/client/26",
        "rel": "client"
      },
      {
        "href": "/form_instance/59028/originator",
        "rel": "originator"
      },
      {
        "href": "/formset_instance/19520",
        "rel": "formset_instance"
      },
      {
        "href": "/formset_instance/19520",
        "rel": "formset"
      }
    ],
    "client_id": 26,
    "closed": false,
    "creation_date": 1404273179,
    "form_id": 3,
    "formset_id": 19520,
    "formset_index": 2,
    "formset_instance_id": 19520,
    "instance_id": 59028,
    "name": "Electrical Work Request",
    "originator_user_id": 1,
    "ref_id": "206069",
    "template_id": 3
  }
]

application/vnd.fb.client+json

Description

This is a collectin of objects representing an individual form. It is only used in responses to GET requests sent to the system, so you should never neeed to construct this collection yourself.

The response is an array of objects, each with the following attributes.

Attributes

invitation+json

application/vnd.fb.invitation+json

{
    "access_level": 3,
    "client_id": 55,
    "contact": "john@email.com",
    "group_id": 12
}

Attributes:

invitations+json

application/vnd.fb.invitations+json; v-1

[
  {
    "_links": [
      {
        "href": "",
        "rel": "client"
      },
      {
        "href": "",
        "rel": "group"
      },
      {
        "href": "",
        "rel": "delete"
      }
    ],
    "access_level": "1",
    "client_id": "5",
    "contact": "info@gotjsolar.com",
    "group_id": "4"
  },
  {
    "_links": [
      {
        "href": "",
        "rel": "client"
      },
      {
        "href": "",
        "rel": "group"
      },
      {
        "href": "",
        "rel": "delete"
      }
    ],
    "access_level": "1",
    "client_id": "5",
    "contact": "primesps@yahoo.com",
    "group_id": "4"
  }
]

Only used with GET Response is an array of objects, each with the following attributes:

member+json

application/vnd.fb.member+json

{
    "access_level": 3,
    "email": "john@email.com",
    "phone": "+333444555",
    "user_id": 64,
    "username": "johnsmith92"
}

Only used for POST

Attribute:

members+json

application/vnd.fb.members+json; 

[
  {
    "access_level": "admin",
    "user_id": 10
  },
  {
    "access_level": "originator",
    "user_id": 11
  }
]

Only used in GET response is an array of objects, each with the following attributes:

pages+json; v=2

application/vnd.fb.pages+json; v=2 

[
  {
    "_links": [
      {
        "href": "/form_instance/5/assignment/0/page/s7IhQxgPg4AuH8-n7FHP-w",
        "rel": "page"
      }
    ],
    "page_id": "s7IhQxgPg4AuH8-n7FHP-w"
  }
]

Only used with GET

An array of object each with the following attributes:

plans+json

application/vnd.fb.plans+json

[
  {
    "base_monthly_charge": 0,
    "payment_tiers": [
      {
        "send_cost": 20,
        "send_count": 0
      }
    ],
    "plan_id": 1,
    "plan_name": "basic plan"
  },
  {
    "base_monthly_charge": 0,
    "payment_tiers": [
      {
        "send_cost": 10,
        "send_count": 0
      },
      {
        "send_cost": 30,
        "send_count": 20
      }
    ],
    "plan_id": 2,
    "plan_name": "advanced plan"
  },
  {
    "base_monthly_charge": 0,
    "payment_tiers": [
      {
        "send_cost": 0,
        "send_count": 0
      }
    ],
    "plan_id": 4,
    "plan_name": "free plan"
  }
]

a plan refers to the details of a subscription that a client has, this will determine how much that client will be charged at the end of each subscription period

a response with this media type will be an array of objects, with each object having the following attributes:

remote_sign+json

application/vnd.fb.remote_sign+json

{
    "email": "john@email.com",
    "field_id": 5
}

Attributes:

Fields marked with an asterix (*) are required for POST requests

remote_signs+json

application/vnd.fb.remote_signs+json

[
    {
        "email": "john@email.com",
        "field_id": 5
    },
    {
        "field_id": 7,
        "phone": "+333444555"
    }
]

Only used in GET

response is an array of objects, each with the following attributes:

role_types+json

application/vnd.fb.role_type+json; v=1

[
  {
    "creation_date": null,
    "name": "Installer",
    "source_id": 1,
    "user_id": 7128
  },
  {
    "creation_date": null,
    "name": "Installer",
    "source_id": 1,
    "user_id": 7317
  }
]

Response is an array of objects with the following attributes:

source+json; v=2

application/vnd.fb.source+json; v=2

{
  "_links": [
    {
      "href": "/client/26/source/476",
      "rel": "self"
    },
    {
      "href": "/client/26/source/476/data",
      "rel": "source_instances"
    },
    {
      "href": "/client/26/source/476/template",
      "rel": "source_templates"
    }
  ],
  "class": "dynamic",
  "client_id": 26,
  "creation_date": 1430016234,
  "last_modified": 1430016274,
  "name": "A Dynamic Abstract",
  "source_id": 476
}

Attributes:

source_map+json; v=2

application/vnd.fb.source_map+json; v=2

{
    "class": "className",
    "closed": false,
    "instance_id": 5,
    "record_id": 12,
    "source_id": 2, 
    "source_reference_id": 1,
    "source_template_id": 2
}

Only used for PUT and POST

Attributes:

source_maps+json; v=2

application/vnd.fb.source_maps+json; v=2

[
  {
    "_links": [
      {
        "href": "/form_instance/6/source_map/0",
        "rel": "self"
      },
      {
        "href": "/client/15/source/1",
        "rel": "source"
      },
      {
        "href": "/client/15/source/1/data/7128",
        "rel": "source_record"
      },
      {
        "href": "/form_instance/6/source_map/0",
        "rel": "source_map"
      }
    ],
    "closed": false,
    "instance_id": 6,
    "record_id": 7128,
    "source_id": 1,
    "source_reference_id": 0,
    "source_template_id": 0
  },
  {
    "_links": [
      {
        "href": "/form_instance/7/source_map/0",
        "rel": "self"
      },
      {
        "href": "/client/15/source/1",
        "rel": "source"
      },
      {
        "href": "/client/15/source/1/data/7128",
        "rel": "source_record"
      },
      {
        "href": "/form_instance/7/source_map/0",
        "rel": "source_map"
      }
    ],
    "closed": false,
    "instance_id": 7,
    "record_id": 7128,
    "source_id": 1,
    "source_reference_id": 0,
    "source_template_id": 0
  },
  {
    "_links": [
      {
        "href": "/form_instance/8/source_map/0",
        "rel": "self"
      },
      {
        "href": "/client/15/source/1",
        "rel": "source"
      },
      {
        "href": "/client/15/source/1/data/7128",
        "rel": "source_record"
      },
      {
        "href": "/form_instance/8/source_map/0",
        "rel": "source_map"
      }
    ],
    "closed": false,
    "instance_id": 8,
    "record_id": 7128,
    "source_id": 1,
    "source_reference_id": 0,
    "source_template_id": 0
  }
]

Only used in GET

Respond is an array of objects with the following attributes:

sources+json; v=2

application/vnd.fb.sources+json; v=2

[
  {
    "_links": [
      {
        "href": "/client/26/source/1",
        "rel": "source"
      },
      {
        "href": "/client/26/source/1/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/1/template",
        "rel": "source_templates"
      }
    ],
    "class": "profile",
    "name": "Installer",
    "type_id": 1
  },
  {
    "_links": [
      {
        "href": "/client/26/source/2",
        "rel": "source"
      },
      {
        "href": "/client/26/source/2/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/2/template",
        "rel": "source_templates"
      }
    ],
    "class": "static",
    "name": "STC Form",
    "type_id": 2
  },
  {
    "_links": [
      {
        "href": "/client/26/source/3",
        "rel": "source"
      },
      {
        "href": "/client/26/source/3/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/3/template",
        "rel": "source_templates"
      }
    ],
    "class": "dynamic",
    "name": "STC Form",
    "type_id": 3
  },
  {
    "_links": [
      {
        "href": "/client/26/source/5",
        "rel": "source"
      },
      {
        "href": "/client/26/source/5/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/5/template",
        "rel": "source_templates"
      }
    ],
    "class": "profile",
    "name": "Designer",
    "type_id": 5
  },
  {
    "_links": [
      {
        "href": "/client/26/source/6",
        "rel": "source"
      },
      {
        "href": "/client/26/source/6/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/6/template",
        "rel": "source_templates"
      }
    ],
    "class": "profile",
    "name": "Abstract",
    "type_id": 6
  },
  {
    "_links": [
      {
        "href": "/client/26/source/7",
        "rel": "source"
      },
      {
        "href": "/client/26/source/7/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/7/template",
        "rel": "source_templates"
      }
    ],
    "class": "dynamic",
    "name": "More",
    "type_id": 7
  },
  {
    "_links": [
      {
        "href": "/client/26/source/476",
        "rel": "source"
      },
      {
        "href": "/client/26/source/476/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/476/template",
        "rel": "source_templates"
      }
    ],
    "class": "dynamic",
    "name": "A Dynamic Abstract",
    "type_id": 476
  },
  {
    "_links": [
      {
        "href": "/client/26/source/999",
        "rel": "source"
      },
      {
        "href": "/client/26/source/999/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/999/template",
        "rel": "source_templates"
      }
    ],
    "class": "profile",
    "name": "Test Abstract",
    "type_id": 999
  }
]

Only used in GET.

Response is an array of objects, each with the following attributes:

source_template+json

application/vnd.fb.source_template+json

{
  "_links": [
    {
      "href": "/client/26/source/476/template/10",
      "rel": "self"
    },
    {
      "href": "/client/26/source/476",
      "rel": "source"
    },
    {
      "href": "/client/26/source/476/template",
      "rel": "source_templates"
    },
    {
      "href": "/client/26/source/476/template/10/data",
      "rel": "source_records"
    },
    {
      "href": "/client/26/source/476/template/10/data",
      "rel": "source_instances"
    },
    {
      "href": "/client/26/source/476/template/10/publish",
      "rel": "publish"
    }
  ],
  "source_id": 476,
  "source_template_id": 10,
  "structure": [
    {
      "field_id": "500",
      "label": "rec_company",
      "name": "Company Name",
      "type": "string"
    },
    {
      "field_id": "1",
      "label": "rec_num",
      "name": "REC Number",
      "type": "string"
    },
    {
      "field_id": "7",
      "label": "city",
      "name": "City",
      "type": "string"
    },
    {
      "field_id": "8",
      "label": "state",
      "name": "State",
      "type": "string"
    },
    {
      "field_id": "9",
      "label": "postalcode",
      "name": "Postcode",
      "type": "integer"
    },
    {
      "field_id": "10",
      "label": "phone",
      "name": "Phone",
      "type": "string"
    },
    {
      "field_id": "11",
      "label": "fax",
      "name": "Fax",
      "type": "string"
    },
    {
      "field_id": "12",
      "label": "mobile",
      "name": "Mobile",
      "type": "string"
    }
  ]
}

Attributes:

source_templates+json

application/vnd.fb.source_templates+json

[
  {
    "_links": [
      {
        "href": "/client/0/source/1",
        "rel": "source"
      },
      {
        "href": "/client/0/source/1/template/0",
        "rel": "source_template"
      },
      {
        "href": "/client/0/source/1/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/0/source/1/template/0/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 0,
    "source_id": 1,
    "source_template_id": 0
  },
  {
    "_links": [
      {
        "href": "/client/0/source/2",
        "rel": "source"
      },
      {
        "href": "/client/0/source/2/template/0",
        "rel": "source_template"
      },
      {
        "href": "/client/0/source/2/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/0/source/2/template/0/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 0,
    "last_modified": 1430450110,
    "source_id": 2,
    "source_template_id": 0
  },
  {
    "_links": [
      {
        "href": "/client/0/source/3",
        "rel": "source"
      },
      {
        "href": "/client/0/source/3/template/0",
        "rel": "source_template"
      },
      {
        "href": "/client/0/source/3/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/0/source/3/template/0/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 0,
    "last_modified": 1430450110,
    "source_id": 3,
    "source_template_id": 0
  },
  {
    "_links": [
      {
        "href": "/client/26/source/476",
        "rel": "source"
      },
      {
        "href": "/client/26/source/476/template/10",
        "rel": "source_template"
      },
      {
        "href": "/client/26/source/476/template/10/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/476/template/10/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 26,
    "source_id": 476,
    "source_template_id": 10
  },
  {
    "_links": [
      {
        "href": "/client/26/source/999",
        "rel": "source"
      },
      {
        "href": "/client/26/source/999/template/0",
        "rel": "source_template"
      },
      {
        "href": "/client/26/source/999/template/0/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/999/template/0/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 26,
    "published": 1428909930,
    "source_id": 999,
    "source_template_id": 0
  },
  {
    "_links": [
      {
        "href": "/client/26/source/999",
        "rel": "source"
      },
      {
        "href": "/client/26/source/999/template/4",
        "rel": "source_template"
      },
      {
        "href": "/client/26/source/999/template/4/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/999/template/4/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 26,
    "published": 1428909930,
    "source_id": 999,
    "source_template_id": 4
  },
  {
    "_links": [
      {
        "href": "/client/26/source/999",
        "rel": "source"
      },
      {
        "href": "/client/26/source/999/template/5000",
        "rel": "source_template"
      },
      {
        "href": "/client/26/source/999/template/5000/data",
        "rel": "source_records"
      },
      {
        "href": "/client/26/source/999/template/5000/data",
        "rel": "source_instances"
      }
    ],
    "client_id": 26,
    "source_id": 999,
    "source_template_id": 5000
  }
]

Only used for GET

Response is an array of objects, each with the following attributes:

subscription+json

application/vnd.fb.subscription+json

{
  "base_monthly_charge": 0,
  "client_id": 34,
  "payment_tiers": [
    {
      "send_cost": 10,
      "send_count": 0
    },
    {
      "send_cost": 30,
      "send_count": 20
    }
  ],
  "plan_id": 2,
  "plan_name": "advanced plan",
  "start_day": 20100901
}

a subscription has details about when a user signed up to a subscription plan Only used for GET

Attribute:

subscriptions+json

application/vnd.fb.subscriptions+json 

[
  {
    "base_monthly_charge": 0,
    "client_id": 34,
    "payment_tiers": [
      {
        "send_cost": 10,
        "send_count": 0
      },
      {
        "send_cost": 30,
        "send_count": 20
      }
    ],
    "plan_id": 2,
    "plan_name": "advanced plan",
    "start_day": 20100901
  },
  {
    "base_monthly_charge": 0,
    "client_id": 34,
    "payment_tiers": [
      {
        "send_cost": 20,
        "send_count": 0
      }
    ],
    "plan_id": 1,
    "plan_name": "basic plan",
    "start_day": 20100201
  }
]

only used in GET response is an array of objects, each with the following attributes:

template+json; v=4

application/vnd.fb.template+json; v=4

{
  "fields": [
    {
      "field_id": 0,
      "font": "5px arial, sans-serif;",
      "left": 431,
      "name": "Suburb/Locality",
      "page_no": 0,
      "source": [
        1,
        5
      ],
      "top": 307,
      "type": "string",
      "width": 196
    },
    {
      "field_id": 1,
      "font": "5px arial, sans-serif;",
      "left": 723,
      "name": "Postcode",
      "page_no": 0,
      "source": [
        1,
        "first_name"
      ],
      "top": 307,
      "type": "integer",
      "width": 132
    },
    {
      "field_id": 63,
      "name": "Access To",
      "options": [
        {
          "left": 780,
          "name": "Meter Position & Switchboard",
          "option_id": 0,
          "top": 553
        },
        {
          "left": 881,
          "name": "PI Lock",
          "option_id": 1,
          "top": 553
        },
        {
          "left": 1043,
          "name": "workmen On Site",
          "option_id": 2,
          "top": 552
        }
      ],
      "page_no": 0,
      "size": 16,
      "type": "multicheckbox"
    },
    {
      "default": 0,
      "field_id": 49,
      "name": "Metering Required",
      "options": [
        {
          "left": 207,
          "name": "Domestic",
          "option_id": 0,
          "top": 874
        },
        {
          "left": 416,
          "name": "Commercial / Industrial",
          "option_id": 1,
          "top": 875
        }
      ],
      "page_no": 0,
      "size": 16,
      "type": "select"
    },
    {
      "field_id": 36,
      "left": 357,
      "name": "Current Transformer Metering",
      "page_no": 0,
      "size": 16,
      "top": 1057,
      "type": "checkbox",
      "width": 12
    },
    {
      "field_id": 6,
      "name": "Have CT's been installed",
      "no": [
        1033,
        1053
      ],
      "page_no": 0,
      "size": 16,
      "type": "yesno",
      "yes": [
        966,
        1054
      ]
    },
    {
      "enabled": "$84",
      "field_id": 5,
      "left": 958,
      "name": "Preferred Time",
      "page_no": 0,
      "top": 1180,
      "type": "time",
      "width": 64
    },
    {
      "field_id": 99,
      "height": 51,
      "left": 335,
      "name": "Registered Address",
      "page_no": 0,
      "top": 1544,
      "type": "text",
      "width": 477
    },
    {
      "field_id": 106,
      "height": 85,
      "left": 256,
      "name": "Signature",
      "page_no": 0,
      "required": true,
      "top": 1602,
      "type": "signature",
      "width": 177
    }
  ],
  "font": "10px tahoma, sans-serif;",
  "pages": [
    {
      "orientation": 90,
      "page_id": "xizVri9zN4d5u5-rsxUQjQ"
    }
  ],
  "roles": [
    {
      "depends": [
        4
      ],
      "label": "installer",
      "role_id": 7,
      "root_section_id": 1,
      "sections": [
        {
          "items": [
            {
              "field_id": 5
            },
            {
              "field_id": 6
            }
          ],
          "section_id": 33
        },
        {
          "items": [
            {
              "field_id": 36
            }
          ],
          "section_id": 1
        }
      ]
    },
    {
      "label": "dummy string",
      "role_id": 4,
      "root_section_id": 0,
      "sections": [
        {
          "items": [
            {
              "field_id": 49
            }
          ],
          "section_id": 0
        },
        {
          "items": [
            {
              "field_id": 63
            }
          ],
          "section_id": 1
        }
      ]
    }
  ],
  "sections": [
    {
      "description": "section description 1",
      "name": "Work Site Address",
      "section_id": 33
    },
    {
      "description": "section description 2",
      "name": "Installation Info",
      "section_id": 1
    },
    {
      "name": "section name 3",
      "section_id": 0
    }
  ],
  "sources": [
    {
      "class": "profile",
      "label": "installer",
      "name": "Default User Type",
      "role_id": 7,
      "source_id": 1,
      "source_reference_id": 1,
      "source_template_id": 0
    },
    {
      "class": "dynamic",
      "label": "stc",
      "name": "STC Form",
      "source_id": 3,
      "source_reference_id": 2,
      "source_template_id": 1
    },
    {
      "class": "dynamic",
      "label": "Rec details",
      "name": "REC Details",
      "source_id": 4,
      "source_reference_id": 3,
      "source_template_id": 3
    }
  ]
}

A template is a like a blank form, from which form_instance can be created and filled with information.

Attributes

templates+json

application/vnd.fb.templates+json

[
  {
    "_links": [
      {
        "href": "/client/26/form/4",
        "rel": "form"
      },
      {
        "href": "/client/26/form/4/version/0",
        "rel": "template"
      },
      {
        "href": "/form/4/version/0/publish",
        "rel": "publish"
      },
      {
        "href": "/form/4/version/0/assignment",
        "rel": "assignments"
      },
      {
        "href": "/form/4/version/0/assignment",
        "rel": "form_assignments"
      },
      {
        "href": "/form/4/cover",
        "rel": "cover"
      },
      {
        "href": "/client/26/form/4/version",
        "rel": "templates"
      }
    ],
    "creation_date": "2010-01-01 10:01:01",
    "form_id": 4,
    "name": "Site Report",
    "published": 1345671941,
    "template_id": 0
  },
  {
    "_links": [
      {
        "href": "/client/26/form/4",
        "rel": "form"
      },
      {
        "href": "/client/26/form/4/version/2",
        "rel": "template"
      },
      {
        "href": "/form/4/version/2/publish",
        "rel": "publish"
      },
      {
        "href": "/form/4/version/2/assignment",
        "rel": "assignments"
      },
      {
        "href": "/form/4/version/2/assignment",
        "rel": "form_assignments"
      },
      {
        "href": "/form/4/cover",
        "rel": "cover"
      },
      {
        "href": "/client/26/form/4/version",
        "rel": "templates"
      }
    ],
    "creation_date": "2010-01-01 10:01:01",
    "form_id": 4,
    "name": "Site Report",
    "published": 1378084047,
    "template_id": 2
  }
]

only used with GET response is an array of objects, each with the following attributes:

transaction+json

application/vnd.fb.transaction+json

{
  "_links": [
    {
      "href": "/client/27/transaction/2",
      "rel": "self"
    },
    {
      "href": "/client/27/",
      "rel": "client"
    }
  ],
  "amount": 100,
  "charges": [
    {
      "_links": [
        {
          "href": "/client/27/",
          "rel": "client"
        },
        {
          "href": "/client/27/transaction/1",
          "rel": "transaction"
        }
      ],
      "amount": 100,
      "base_subscription_amount": 0,
      "bonus_sends_after": 0,
      "bonus_sends_before": 0,
      "charge_id": 1,
      "client_id": 27,
      "currency": "AUD",
      "end_day": "20100301",
      "start_day": "20100201",
      "tier_limits": [
        {
          "send_cost": 50,
          "send_count": 100
        },
        {
          "send_cost": 30,
          "send_count": 500
        },
        {
          "send_cost": 15,
          "send_count": 4294967296
        }
      ],
      "total_instances": 2,
      "transaction_id": 2
    }
  ],
  "client_id": 27,
  "currency": "AUD",
  "date": 1441259992,
  "successful": 1,
  "transaction_id": 2
}

a transaction contains details for every time a client’s credit card is charged Only used for GET

Attributes:

transactions+json

application/vnd.fb.transactions+json

[
  {
    "_links": [
      {
        "href": "/client/29/transaction/5",
        "rel": "self"
      },
      {
        "href": "/client/29/",
        "rel": "client"
      }
    ],
    "amount": 100,
    "client_id": 29,
    "currency": "AUD",
    "date": 1441260000,
    "successful": 0,
    "transaction_id": 5
  },
  {
    "_links": [
      {
        "href": "/client/29/transaction/3",
        "rel": "self"
      },
      {
        "href": "/client/29/",
        "rel": "client"
      }
    ],
    "amount": 100,
    "client_id": 29,
    "currency": "AUD",
    "date": 1441259993,
    "successful": 0,
    "transaction_id": 3
  }
]

only used in GET response is an array of objects, each with the following attributes:

usage+json

application/vnd.fb.usage+json

{
  "_links": [
    {
      "href": "/client/26/view",
      "rel": "client"
    },
    {
      "href": "/monthly_charge/26/index",
      "rel": "monthly_charge"
    },
    {
      "href": "/transaction/26/index",
      "rel": "transaction"
    }
  ],
  "balance_brought_forward": [
    {
      "USD": 100
    },
    {
      "AUD": 100
    }
  ],
  "base_monthly_charge": 0,
  "count_sends": 2,
  "cumulative_owing": [
    {
      "USD": 100
    },
    {
      "AUD": 100
    }
  ],
  "currency": "AUD",
  "free_sends_remaining": 88,
  "mtd_cost": 0,
  "tier_limits": [
    {
      "send_cost": 20,
      "send_count": 0
    }
  ]
}

Only used in GET

Attributes:

examples