apidocumentation.tractivity.co.uk Open in urlscan Pro
3.215.255.119 Public Scan

Back to summary
URL:
https://apidocumentation.tractivity.co.uk/
Submission: On October 10 via automatic, source certstream-suspicious (October 10th 2021, 10:02:06 am UTC) — Scanned from DE
Form analysis
0 forms found in the DOM

Text Content

Public


Documentation Settings
Environment
Documentation
Layout
Double Column
Language
cURL



TRACTIVITY API

 * Introduction
 * Technologies
 * Where to Start


API Structure

Examples
Tractivity API

Thank you for choosing Tractivity, this documentation will guide you through how
to connect to, authenticate with the Tractivity API, and how to interact with
data in Tractivity using the API.

If you have any questions which cannot be answered by the documentation, please
contact us at support@tractivity.co.uk.

The Tractivity API is under continual development, if there is a feature which
you require which has not yet been added please contact your account manager or
email us at support@tractivity.co.uk.


TECHNOLOGIES

All connections to the Tractivity API require HTTPS connections.

Requests made to the Tractivity API are consistent with the HTTP Request
methods. Currently only GET, POST and PUT are supported.

All data sent to the API in the body of a request or returned from the API in
the body of a response will be in the JSON format.

Authorisation is performed using OAuth 2.0.


WHERE TO START

All of the endpoints in the Tractivity API will have the same root URL of the
format:
"https://clientname.tractivity.co.uk/API/V1".
So for example if the ACME corporation had a tractivity system the root URL
would be:
"https://acme.tractivity.co.uk/API/V1".

Once you have determined your Tractivity API URL, attempt to Authenticate with
the Tractivity API.

Examples of how to use the Tractivity API for common use cases can be found in
the Examples section.

If there is not an example for your particular use case then you can examine the
API Structure for a complete list of operations and data structures

AUTHORIZATIONOAuth 2.0
Access Token
<access-token>


API Structure

This section lists all the requests which can be made to the API. Once you have
Authenticated you will need to choose which Project you are working with.


ENTITIES

Once you have a Project ID you can begin to interact with the major Entities
within each Project such as

   
 * Building
   
 * Organisations
   
 * Organisation Activities
   
 * Organisation Addresses
   
 * Contacts
   
 * Contact Activities
   
 * Contact Addresses
   
 * Enquiries
   
 * Enquiry Activities
   
 * Events
   
 * Event Activities
   

Each Entity includes a definition of that Entity consisting of a list of
properties. The definition will also state what data type the property uses, any
restrictions on the possible values for that property and if that property is
required when submitting POST or PUT requests.

Each Entity inlcudes a list of requests which can be made to interact with that
Entity.


FIELDS


DESCRIPTION

Every Entity type will have properties of type Field. A Field in the Tractivity
API is used to represent a possible value for a property where that property
will only accept a pre-determined list of values.

For example in an HTML Form a property of type Field would be represented by a
Select element, and each Field would be an HTML Option element within the Select
element. A property of type "Array of Field" would be a Select element which
allowed multiple values to be selected.

Every entity has a request which can be used to fetch the available Fields for
that data type e.g. Get Enquiry Fields or Get Contact Fields.


SCHEMA

Property Data Type Required

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Authentication

Access to the Tractivity API is authenticated using OAuth 2.0. Currently only
the Client Credentials grant type is supported.


POST

Get Token using Client Credentials

https://acme.tractivity.co.uk/API/V1/token

For the Client Credentials grant type instead of accessing the API with
Tractivity user credentials, a seperate type of credentials is used which
specifically represents the application you are using to consume the Tractivity
API.

Client credentials are created and managed within the Tractivity system by
Tractivity users with System Administrator permissions, and are referred to
within the Tractivity system as API Credentials. When creating the API
Credentials in Tractivity, the credentials intially do not have access to any
data, please ensure that access to the appropriate Projects is added to the API
Credentials. If required it is also possible to add IP restrictions to API
Credentials such that only specific IP Addresses are allowed to access your
Tractivity API using those API Credentials.

Please ensure that your API Credentials are kept secret. They must never be
exposed on client-side applications such as in Javascript on a web page. If you
believe that the API Credentials have been compromised, then you can reset the
secret and if neccessary deactivate the API Credentials to prevent access to the
API with those credentials.

You can use your API credentials to authenticate with the Tractivity API as
shown in this request.

Submit a POST request to the "token" endpoint providing the API credentials in
the format specified in HTTP Basic authentication. This involves:

    
 1. instantiate an HTTP POST request to the "token" endpoint e.g.
    "https://acme.tractivity.co.uk/API/V1/Token".
    
 2. Concatenate the API Credentials ClientID and secret into a single string in
    the format "ClientID:secret".
    
 3. Base64 encode the string.
    
 4. Add an HTTP Authorization header with a value of "Basic" + the enconded
    string.
    
 5. Add a JSON body to the request which specifies that you are using the Client
    Credentials grant type.
    

If authenticated successfully the Tractivity API returns a token, which allows
access to the entire API without the need to re-authenticate until the token
expires. The time until expiry is returned in seconds in the response body as
the JSON property "expires_in". This token is used by adding it to further
requests as an HTTP request header e.g. Authorization: Bearer
ce7625bf-6eb4-41ab-8607-7d08cbe20776.

20 minutes after requesting the token it will expire, and you will need to
request a new token.

HEADERS
Authorization
Basic
MjgwYzk4NWUtMmIzNi00Yjg1LWFlNWMtMjhmOTYyYWNhM2ViOmJEUEVHPkVmLjBJWygqTyFHWWZuYntJXQ==
BODYraw

grant_type=client_credentials



Example Request
Success

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--header 'Authorization: Basic MjgwYzk4NWUtMmIzNi00Yjg1LWFlNWMtMjhmOTYyYWNhM2ViOmJEUEVHPkVmLjBJWygqTyFHWWZuYntJXQ==' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "7ff7a306-b0d2-4374-a484-057d5d8fa117",
  "token_type": "bearer",
  "expires_in": 1199
}

Request Validation & Error Handling


BAD REQUEST VALIDATION

Any data submitted to the API via a request will be processed through several
internal validation rules. Any failed requests are returned as a 400 Bad Request
with details of the specific data that is invalid.


400 RESPONSE SCHEMA


{
    "message": "The request is invalid.",
    "modelState": {
        validation Message: [
            Validation Description
        ]
    }
}



ERROR HANDLING POLICY

If an exception occurs whilst a request is being processed Tractivity will log
the exception and the support team are alerted to the error, the response for
that request is returned as a code 500. We recommend that further exception
handling is implement within the application that is referencing the Tractivity
API to display appropriate client facing content.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Rate Limiting

The Tractivity API is rate limited, in order to prevent Tractivity becoming
overloaded by the sheer number of requests.

The limits are as follows:

   
 * 9 requests per second.
   
 * 360 requests per minute.
   

For any Attachment endpoints when returning the Attachment byte data this is
reduced due to the amount of data which can be returned and the intensity of the
query to the following:

   
 * 1 request per second.
   
 * 30 requests per minute.
   

If you exceed these limits you will receive a 429 response including a messaging
how long you have to wait until you can make the request again.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Projects


DESCRIPTION

All data in Tractivity is contained within a Project. A Project represents a
discrete piece of work which your organisation is undertaking for which you are
using Tractivity to manage your interactions with stakeholders. This for example
may be building a powerplant or running a campaign to raise awareness of a
particular issue. A Tractivity system can have many Projects.

####

View More

Property DataType Required id Integer Yes title string No

The following Entities can be shared between Projects.

   
 * Contacts
   
 * Organisations
   
 * Buildings
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Buildings


DESCRIPTION

A Building represents a physical property. A Building can be linked to
Organisations and Contacts as Addresses. A Building is seperate from an Address
in that:

   
 * Multiple Contacts or Organisations can have an Address using the same
   Building, for instance multiple Contacts in different flats in the same
   block.
   
 * Addresses may be recorded as previous addresses, and are not necessarily the
   current Address.
   
 * It is possible for Contacts and Organisations to have different relationships
   to the Building, for example a Contact could be a tenant in a flat and an
   Organisation is the Freeholder of the flat.
   


PROJECT SHARING

   
 * Buildings can be shared between Projects.The Projects a Building is shared
   with is determined by the Projects property.
   
 * A Building has no Project Specific properties which is to say that all of a
   Building's properties are constant across all the Projects the Building is
   shared with.
   
 * Automatic Project Sharing - If a Contact or an Organisation is shared to a
   Project then all Buildings which are related to that Contact or Organisation
   through an Address are automatically shared to that Project
   


SCHEMA

View More

Property DataType Required Restrictions Project Specific id Integer No None No
buildingNameNumberRoad string Yes Maximum Length 256 Characters No postcode
String Yes Maximum length 19 characters No locality String No Maximum Length 256
Characters No town string Yes Maximum Length 128 Characters No county string No
Maximum Length 128 Characters No state Field No Maximum Length 128 Characters No
country Field No None No buildingType Field No None No longitude Decimal No 6
decimal places No latitude Decimal No 6 Decimal Places Yes uprn String No
Maximum length 12 characters No distanceFromProject Field No Maximum Length 128
Characters No projects Array of Project No None No

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get all Buildings for project


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings?pageIndex=1&pageSize=2

The Request takes the format "{RootURL}/Projects/{ProjectID}/Buildings".

This method fetches a paged list of all buildings within the Project specified
by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
1

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
2

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Success
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings'

Example Response
200 OK
Body
Header(3)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 2074,
      "postcode": "S9 1TL",
      "buildingNameNumberRoad": "Foundary Road",
      "locality": "The Mills",
      "town": "Sheffield",
      "county": "South Yorkshire",
      "country": {

GET

Get Building


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/2076

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Buildings/{BuildingID}"

Where the BuildingID is the ID of the Building to select, and the ProjectID is
the ID of the Project the Building is in.

Fetches a single Building.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/2076'

Example Response
200 OK
Body
Header(3)
View More

{
  "id": 2076,
  "postcode": "s611aa",
  "buildingNameNumberRoad": " Union Street",
  "locality": "",
  "town": "Rotherham",
  "county": "South Yorkshire",
  "country": {
    "id": 232,
    "title": "United Kingdom"
  },

GET

Get Building Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Fields?include=buildingTypes&include=countries

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Buildings/Fields"

Where the ProjectID is the ID of the Project to select data for.

Fetches the Building Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
PARAMS
include
buildingTypes
include
countries


Success - all fields
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Fields' \
--header 'Content-Type: application/json'

Example Response
200 OK
Body
Header(3)
View More

{
  "towns": [
    {
      "id": 221,
      "title": "Abram"
    },
    {
      "id": 47,
      "title": "Altrincham"
    },
    {

POST

Find Building Duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Buildings/Duplicates". Where the ProjectID is
the ID of the Project to select data for.

This request will Fetch all Buildings in the Project which have the same
postcode, and whose building name, number or road contain the supplied value


SCHEMA

View More

Property Required Postcode Yes buildingNameNumberRoad Yes

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "postcode": "DE451GT",
    "buildingNameNumberRoad": "systems"
}



Success - no duplicates
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "postcode": "S101HQ",
    "buildingNameNumberRoad": "14"
}'

Example Response
200 OK
Body
Header(6)

[]

POST

Add Building


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Buildings".
Where the ProjectID is the ID of the Project to add a Building to.

Building Schema

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
PARAMS
projectID
11
BODYraw
View More

{
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "12 Carver Street",
    "locality": "",
    "town": {
        "id": 2
    },
    "county": {
        "id": 31
    },
    "country": {



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '{
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "12 Carver Street",
    "locality": "",
    "town": {
        "id": 2
    },
    "county": {
        "id": 31

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 2079,
  "postcode": "S1 4FS",
  "buildingNameNumberRoad": "12 Carver Street",
  "locality": "",
  "town": "Bakewell",
  "county": "Derbyshire",
  "country": {
    "id": 232
  },
  "buildingType": {

PUT

Update Building


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Buildings".
Where the ProjectID is the ID of the Project to update a Building in.

The ID property of the Building in the Request body specifies the Building to
update.

All properties of the Building are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the Building

Building Schema

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 2079,
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "EnerCom HQ, 12 Carver Street",
    "locality": "",
    "town": {
        "id": 2
    },
    "county": {
        "id": 31
    },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 2079,
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "EnerCom HQ, 12 Carver Street",
    "locality": "",
    "town": "Bakewell",
    "county": "Derbyshire",
    "country": {
        "id": 232

Example Response
200 OK
Body
Header(3)
No response body
This request doesn't return a response body

Organisations


DESCRIPTION

An Organisation represents a group with whom you have interacted with, or will
need to interact with in order to run your Project. An Organisation could be one
or several of the following:

   
 * A Company.
   
 * A Charity.
   
 * A Political party.
   
 * A consumer group.
   

PROJECT SHARING

   
 * Organisations can be shared across Projects.
   
 * Certain properties can contain different values for each project. These
   properties are labelled as Project Specific in the below Schema.
   
 * You can specify the Projects the Organisation is shared with using the
   Projects property.
   

It is possible that a Client may engage with the same Organisation across
different Projects. For example the Organisation "Transport for London" would
need to be engaged with on any Project that would require road works or road
closures within the city of London. In this instance, the Client would add
"Transport for London" once, and then share this Organisation with any other
Projects as and when the engagement happens. When Organisations are shared
across multiple Projects, there are some properties that store the same
information across all Projects, for example, Organisation Name, Address, Email,
Telephone or Organisation Category and there are some properties that are
assigned Project-specific values. For example, "Transport for London" may have a
Stakeholder Category of ‘Statutory Stakeholder’ and they may be subscribed to
receive the mailshots for Project A, but in Project B they could be considered
to be a ‘Non-Statutory Stakeholder’ and be unsubscribed from Mailshot
communications.


SCHEMA

View More

Property DataType Required Restrictions Project Specific id Integer No None No
name String Yes Maximum length 256 No telephone String No Maximum length 50 No
websiteUrl String No Maximum length 512 No email String No Maximum length 128 No
notes String No None No quickNotes String No None No accountHandler Field No
None Yes telephone2 String No Maximum length 50 No email2 String No Maximum
length 50 No mobile String No Maximum length 50
Non-UK numbers require the relevant area code prefix as without a code all
entries will default to the UK area code (44) No linkedInUrl String No Maximum
length 512 No twitterUrl String No Maximum length 512 No facebookUrl String No
Maximum length 512 No youtubeUrl String No Maximum length 512 No googlePlusUrl
String No Maximum length 512 No contactPermitted Array of Field No None No
legalStatus Field No None No tradingStatus Field No None No registrationNumber
String No Maximum length 256 No turnover Decimal No None No numberOfEmployees
Integer No None No stakeholderCategories Array of Field No None Yes
organisationSector Field No None No organisationsCategories Field No None No
organisationSubCategories Array of Field No None No projectCategories Field No
None Yes projectSubCategories Array of Field No None Yes organisationRegions
Array of Field No None Yes accountGroups Array of Field No None Yes
distributionLists Array of String No This property is read only. No
mailshotSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes
postalSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes
telephoneSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes
smsSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes projects Array of
Project No None No


SUBSCRIPTION PREFERENCE

DESCRIPTION

The Subscription Preference data type represents a record of whether or not an
Organisation has been asked if they would like to receive marketing
communications, and their answer.

SCHEMA

View More

Property Data Type Required Notes id Integer No **N.B.** Excluding the ID will
create a new Subscription Preference record.
Adding the ID, even on a PUT request will not create a new record, but will
instead keep the existing record.
createdDate String in the format
yyyy-MM-ddTHH:mm:ss
e.g. 2019-02-20T17:17:20 Yes createdByText String Yes The name of individual
submitting the preference createdByURL String No If this preference has been
updated through a website, this is the URL of the page.
This information can only be added on a POST or PUT, and is not retreived on a
GET request. createdByIPAddress String No If this preference was created by an
HTTP request, this is the client IP address of that request.
This information can only be added on a POST or PUT, and is not retreived on a
GET request. createdByUserAgent String No If this preference was created by an
HTTP request, this is the User Agent address of that request.
This information can only be added on a POST or PUT, and is not retreived on a
GET request. status Field Yes method Field No -if the Status is "No Response",
otherwise Yes

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Activities


DESCRIPTION

Activities represent actions taken within the Tractivity system. Their purpose
is to record what has been done by Tractivity Users, Organisations or Contacts.
Activities can also be used to prompt Tractivity Users that action needs to be
taken with regards to specific Organisations, Contacts or Enquiries. These
actions can include:

   
 * A Contact requesting information about a project via a website.
   
 * An Email being sent in response to an Enquiry.
   
 * A Scheduled meeting with an Organisation.
   


SCHEMA

View More

Property DataType Required Restrictions id Integer No None title String Yes None
activitySubType Field Yes None status Field Yes None notes String No None
agreementNotes String No None ownerTeams Array of Field No (If no values
supplied, the Project's default team is used) None allocatedToTeams Array of
Field No (If no values supplied, the Project's default team is used) None
startDate String Yes yyyy-mm-dd endDate String Yes yyyy-mm-dd startTime String
No hh:mm:ss endTime String No hh:mm:ss stakeholderCategory Field No None
activityAmount Integer No None accountGroups Array of Field No None Yes
subProject Field No None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Attachments

View More

Property Data Type Comments ID Int Filename string FileExtension string e.g.
".pdf" OriginalFilename string FileSize string Human readable description of
file size e.g. 2.3Mb or 530Kb FileAsByteArray array of byte This is only
populated if the IncludeData=main querystring parameter is included in the URL
FileSizeInBytes int Length of FileAsByteArray MimeType string

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Activities/1078/Attachments?pageIndex=1&pageSize=1

URL in the form
{BaseURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Activities/{ActivityID}/Attachments.

Returns a paged list of Attachments for the specified activity. These
attachments do not include the file data itself, just the metadata.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
1

Optional - the index of the page to return, starts at 0

pageSize
1

Optional - the maximum number of results to return in a single response. The
default & maximum is 15.



Successful, default paging
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Activities/1078/Attachments'

Example Response
200 OK
Body
Header(5)
View More

{
  "recordCount": 2,
  "pageCount": 1,
  "results": [
    {
      "id": 1631,
      "filename": "Large Attachment - under limit",
      "fileExtension": ".zip",
      "originalFilename": "Large Attachment - under limit",
      "fileSize": "26Mb",
      "fileAsByteArray": "",

GET

Get Attachment


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Activities/1078/Attachments/1635?includeData=main

URL in the form
{BaseUrl}/Projects/{ProjectID}/Organisations/{OrganisationID}/Activities/{ActivityID}/Attachments/{AttachmentID}

If you include the querystring parameter includeData=main then the file data as
bytes will be returned. If not then only the meta data is returned.

This request is rate limited to:

   
 * once per second
   
 * 30 times per minute
   

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
includeData
main

Optional - if this parameter is included then the fileAsByteArray property is
populated.



Successful, with fileAsByteArray
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Activities/1078/Attachments/1635?includeData=main'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 1635,
  "filename": "Spec Format_2014-04-14 doc version",
  "fileExtension": ".doc",
  "originalFilename": "Spec Format_2014-04-14 doc version",
  "fileSize": "261Kb",
  "fileAsByteArray": "0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAAAAAAEAAAA+AEAAAAAAAAAEAAA+wEAAAEAAAD+////AAAAAPQBAAD1AQAA9gEAAPcBAAD////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////spcEAGQAJBAAA+BK/AAAAAAAAEAAAAAAACAAASQoAAA4AYmpiauD74PsAAAAAAAAAAAAAAAAAAAAAAAAJBBYAlEwBAIKRumeCkbpn7wEAAAAAAAA+AAAAAAAAAAAAAAAAAAAAAAAAABsAAAD//w8AAAAAAAAAAAD//w8AAAAAAAAAAAD//w8AAAAAAAAAAAAAAAAAAAAAALcAAAAAAPIMAAAAAAAA8gwAAIQaAAAAAAAAhBoAAAAAAAAcGwAAAAAAABwbAAAAAAAAHBsAABQAAAAAAAAAAAAAAP////8AAAAAMBsAAAAAAAAwGwAAAAAAADAbAAA4AAAAaBsAADQAAACcGwAAXAAAADAbAAAAAAAAiFEAAKoDAAD4GwAAAAAAAPgbAAAoAAAAIBwAAAAAAAAgHAAAAAAAACAcAAAAAAAAIzYAAAAAAAAjNgAAAAAAACM2AAAAAAAAB1EAAAIAAAAJUQAAAAAAAAlRAAAAAAAACVEAAAAAAAAJUQAAAAAAAAlRAAAAAAAACVEAACQAAAAyVQAAtgIAAOhXAABiAAAALVEAABUAAAAAAAAAAAAAAAAAAAAAAAAAHBsAAAAAAAAjNgAAAAAAAAAAAAAAAAAAAAAAAAAAAACnNQAAAAAAAKc1AAB8AAAAIzYAAAAAAAAjNgAAAAAAAC1RAAAAAAAAAAAAAAAAAACEGgAAAAAAAIQaAAAAAAAAIBwAAAAAAAAAAAAAAAAAACAcAACHGQAAQlEAABYAAAD7NwAAAAAAAPs3AAAAAAAA+zcAAAAAAAAjNgAAUgAAAIQaAAAAAAAAIBwAAAAAAACEGgAAbAAAACAcAAAAAAAAB1EAAAAAAAAAAAAAAAAAAPs3AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIzYAAAAAAAAHUQAAAAAAAAAAAAAAAAAA+zcAAAAAAAD7NwAAcgAAAOlAAABUAAAAAAAAAAAAAADwGgAALAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA6UEAAAAAAAAgHAAAAAAAAP////8AAAAAwIqLmFlj1wEAAAAAAAAAAP////8AAAAAdTYAAGoAAAA9QQAADgAAAAAAAAAAAAAA81AAABQAAABYUQAAMAAAAIhRAAAAAAAAS0EAAJ4AAABKWAAAAAAAAN82AACsAAAASlgAABwAAADpQQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADpQQAAagIAAEpYAAAAAAAAAAAAAAAAAAAcGwAAAAAAAFNEAACgDAAAIzYAAAAAAAAjNgAAAAAAAPs3AAAAAAAAIzYAAAAAAAAjNgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIzYAAAAAAAAjNgAAAAAAACM2AAAAAAAALVEAAAAAAAAtUQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAizcAAHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACM2AAAAAAAAIzYAAAAAAAAjNgAAAAAAAIhRAAAAAAAAIzYAAAAAAAAjNgAAAAAAACM2AAAAAAAAIzYAAAAAAAAAAAAAAAAAAP////8AAAAA/////wAAAAD/////AAAAAAAAAAAAAAAA/////wAAAAD/////AAAAAP////8AAAAA/////wAAAAD/////AAAAAP////8AAAAA/////wAAAAD/////AAAAAP////8AAAAA/////wAAAAD/////AAAAAP////8AAAAA/////wAAAAD/////AAAAAEpYAAAAAAAAIzYAAAAAAAAjNgAAAAAAACM2AAAAAAAAIzYAAAAAAAAjNgAAAAAAACM2AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAjNgAAAAAAACM2AAAAAAAAIzYAAAAAAADyDAAAWAwAAEoZAAA6AQAABQASAQAACQgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAENDQ1DbGllbnQgTmFtZQcHRG9jdW1lbnQgVGl0bGUHB1Byb3Bvc2FsBwdDcmVhdGVkIJYgTWFyayBSdXR0ZXIgKDExdGggRmVicnVhcnkgMjAxNCkNRWRpdGVkIJYgTWFyayBSdXR0ZXIgKDE5dGggTWFyY2ggMjAxNCkHBw0MDTAxIFNlY3Rpb24NRGV0YWlsDQ0NMTIgQ29zdCBFc3RpbWF0ZQ0NVGhpcyBlc3RpbWF0ZSBpcyBiYXNlZCBvbiBvdXIgY3VycmVudCB1bmRlcnN0YW5kaW5nIG9mIHJlcXVpcmVtZW50cyBhbmQgbWF5IGNoYW5nZSBpZiBmdXJ0aGVyIGZ1bmN0aW9uYWxpdHkgaXMgaWRlbnRpZmllZC4gDVJlc2VhcmNoLCBkZXNpZ24gJiBidWlsZCBhY3Rpdml0eQdEYXlzB0Nvc3QHB0RlZmF1bHQgT3duZXIgVGVhbXMHBwcHBwcHB1RvdGFsIGRlc2lnbiAmIGRldmVsb3BtZW50BwejBwdQcm9qZWN0IG1hbmFnZW1lbnQHBwcHVG90YWwgcHJvamVjdCBjb3N0IChleGNsLiBWQVQpBwcHBw1QbGVhc2Ugbm90ZTsNCUFsbCBDb3N0cyBhcmUgZXhjbHVkaW5nIFZBVA0JDQMNDQQNDQMNDQQNDVBhZ2UgEyBQQUdFIBQyFSBvZiATIE5VTVBBR0VTICAUMhUNDQ0NDQ0IDQgIDQ0IDQ0NDQ13d3cucmUtc3lzdGVtcy5jby51aw0NDQ0NDQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAQgAAAIIAAADCAAA

GET

Get all Activities for Organisation


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Activities"

This method fetches a paged list of all Activities for an Organisation specified
by the OrganisationID within the Project specified by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0
pageSize
2


Success, specific paging parameters
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Activities?pageIndex=0&pageSize=2'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1924,
      "title": "Details Update",
      "activitySubType": {
        "id": -15,
        "title": "Email Received"
      },
      "status": {

GET

Get Organisation Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Activities/1924

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Activites/{ActivityID}"

Where the ProjectID is the ID of the Project to select data for, the
OrganisationID is the ID of the Organisation the Activity is for and the
ActivityID is the ID of the Activity to select

Fetches a single Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get Activity

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Activities/1924'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1924,
  "title": "Details Update",
  "activitySubType": {
    "id": -15,
    "title": "Email Received"
  },
  "status": {
    "id": 2,
    "title": "Completed"
  },

GET

Get Organisation Activity fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Activities/Fields?

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Fields"

Where the ProjectID is the ID of the Project to select data for, and the
OrganisationID is the ID of the Organisation you need to select data for.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activityStatuses


Success - Specific Fields only
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Activities/Fields?include=activityStatuses'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ]

POST

Add Organisation Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/42/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Activities".

Where the ProjectID is the ID of the Project to add an Activity to and the
OrganisationID is the ID of the specific Organisation within that Project to add
the Activity to.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Website Request for more information",
    "activitySubType": {
            "title": "Follow-Up",
            "id": 1028
        },
    "status": {
        "id": 2,
        "title": "Completed"
    },
    "notes": "We would like to receive more information about this Project",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/42/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Website Request for more information",
    "activitySubType": {
            "title": "Follow-Up",
            "id": 1028
        },
    "status": {
        "id": 2,
        "title": "Completed"

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 1929,
  "associatedContactIDs": [],
  "title": "Website Request for more information",
  "activitySubType": {
    "id": 1028,
    "title": "Follow-Up"
  },
  "status": {
    "id": 2,
    "title": "Completed"

PUT

Update Organisation Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/42/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Activities".
Where the ProjectID is the ID of the Project to update a Building in and the
OrganisationID is the ID of the Organisation to which the Activity you are
updating belongs.

The ID property of the Activity in the Request body specifies the Activity to
update.

All properties of the Activity are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the Activity

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 1929,
    "associatedContactIDs": [],
    "title": "Website Request for more information",
    "activitySubType": {
        "id": 1028,
        "title": "Follow-Up"
    },
    "status": {
        "id": 2,
        "title": "Completed"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/42/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1929,
    "associatedContactIDs": [],
    "title": "Website Request for more information",
    "activitySubType": {
        "id": 1028,
        "title": "Follow-Up"
    },
    "status": {

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body

Addresses


DESCRIPTION

An Address links an Organisation to a Building The Address Entity holds any
information that is specific to that Organisation’s relationship with a
particular building record, for example if the Organisation is the owner or a
tenant of the building and when they began using the address. An Organisation
can have multiple Addresses in the same Building and in seperate Buildings. You
can record previous Addresses by setting an Address as Detached.


PROJECT SHARING

If the Organisation is shared with a Project, then the Address & Building are
automatically shared with that Project.


SCHEMA

View More

Property DataType Required Restrictions id Integer No None unitNumber String No
Maximum length 128 building Building Yes Only the Building ID property is
required. relationship Field No None startDate String No yyyy-mm-hh detached
bool No None defaultAddress bool Yes None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get all Addresses for Organisation


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Addresses"

This method fetches a paged list of all Addresses for an Organisation specified
by the OrganisationID within the Project specified by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
1

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
2

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Success, specific paging parameters
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses?pageIndex=1&pageSize=2'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 2,
  "results": [
    {
      "unitNumber": "Units 1-18",
      "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": {

GET

Get Organisation Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/2053

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Addresses/{AddressID}"

Where the ProjectID is the ID of the Project to select data for, the
OrganisationID is the ID of the Organisation the Address is for and the
AddressID is the ID of the Address to select

Fetches a single Address.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/2053'

Example Response
200 OK
Body
Header(6)
View More

{
  "unitNumber": "Units 2-14",
  "building": {
    "id": 2075,
    "postcode": "Ng18 2HT",
    "buildingNameNumberRoad": "8 Cliff Street",
    "locality": "",
    "town": {
      "id": 239,
      "title": "Mansfield"
    },

GET

Get Organisation Address fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Fields"

Where the ProjectID is the ID of the Project to select data for and the
OrganisationID is the ID of the Organisation to select data for.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "relationships": [
    {
      "id": 3,
      "title": "Building Manager"
    },
    {
      "id": 1,
      "title": "Building Owner"
    },
    {

POST

Find Organisation Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Addresses/Duplicates".
Where the ProjectID is the ID of the Project to select data for, the
OrganisationID is the ID of the Organisation to select date for.

This request will fetch all Addresses for the specified Organisation where the
Address is for the same Building and the Address unitNumber contains the
unitNumber specified in the request body.


SCHEMA

View More

Property Required unitNumber Yes building.id Yes

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "15",
    "building": {
        "id": 2075
    }
}



Success, no duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "15",
    "building": {
        "id": 2075
    }
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Organisation Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Addresses". Where
the ProjectID is the ID of the Project to update an Address in. The
OrganisationID is the ID of the Organisation the Address being updated belongs
to.

The ID property of the Address in the Request body specifies the Building to
update.

All properties of the Address are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the Address

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Organisation Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/27/Addresses

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}/Addresses". Where
the ProjectID is the ID of the Project to add an Address to. The OrganisationID
is the ID of the Organisation the Address will be added to.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "",
    "building": {
        "id": 31
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },

Example Response
201 Created
Body
Header(7)
View More

{
  "unitNumber": "Units 15-20",
  "building": {
    "id": 2075,
    "postcode": "Ng18 2HT",
    "buildingNameNumberRoad": "8 Cliff Street",
    "locality": "",
    "town": {
      "id": 239,
      "title": "Mansfield"
    },

GET

Get all Organisations for project


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations?pageIndex=1&pageSize=1

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Orgnaisations"

This method fetches a paged list of all Orgnaisations within the Project
specified by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
1

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
1

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Success
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations'

Example Response
200 OK
Body
Header(2)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 51,
      "name": "Sheffield Turbines LTD",
      "telephone": "0114 254657",
      "websiteUrl": "www.sheffieldturbines.com",
      "email": "info@sheffieldturbines.co.uk",
      "notes": "This company is quite an important supplier",
      "accountHandler": {

GET

Get Organisation


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/{OrganisationID}"

Where the ProjectID is the ID of the Project to select data for, and the
OrgnaisaionID is the ID of the Orgnaisation to select

Fetches a single Organisation.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 51,
  "name": "Sheffield Turbines LTD",
  "telephone": "0114 254657",
  "websiteUrl": "www.sheffieldturbines.com",
  "email": "info@sheffieldturbines.co.uk",
  "notes": "This company is quite an important supplier",
  "accountHandler": {
    "id": 2125,
    "name": "Stoke, Mark"
  },

GET

Get Organisation Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Fields?include=organisationCategories&include=organisationSubCategories

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/Fields"

Where the ProjectID is the ID of the Project to select data for.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
organisationCategories
include
organisationSubCategories
include
stakeholdercategories


Success - all fields
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "accountHandlers": [
    {
      "id": 2122,
      "name": "Arthurs, Jamie"
    },
    {
      "id": 2126,
      "name": "Speaker, Adam"
    },
    {

POST

Find Organisation duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Organisations/Duplicates". Where the ProjectID
is the ID of the Project to select data for.

This request will Fetch all Organisations in the Project whose name contains the
supplied name. If a postcode is specified in the request, then the returned
Organisations must also have an attached Address at the same postcode.


SCHEMA

View More

Property Required name Yes postcode no

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "name": "Doncaster Sheffield Airport"
}



Example Request
Success

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Doncaster Sheffield Airport"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 52,
    "name": "Doncaster Sheffield Airport",
    "telephone": "0114 565845",
    "websiteUrl": "flydsa.co.uk",
    "email": "info@flydsa.co.uk",
    "notes": "",
    "accountHandler": {
      "id": 2122,
      "name": "Arthurs, Jamie"

POST

Add Organisation


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Organisations".
Where the ProjectID is the ID of the Project to add an Organisation to.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"
        },
    "telephone2": "0114 646489",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 55,
  "name": "Tractivity Limited",
  "telephone": "01629 815914",
  "websiteUrl": "tractivity.co.uk",
  "email": "support@tractivity.co.uk",
  "notes": "",
  "accountHandler": {
    "id": 2125,
    "name": "Stoke, Mark"
  },

PUT

Update Organisation


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Organisations".
Where the ProjectID is the ID of the Project to update an Organisation in.

The ID property of the Building in the Request body specifies the Organisation
to update.

All properties of the Organisation are overwritten with the supplied values. If
no values are supplied for a property, that property is set to null on the
Organisation.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,
        "name": "Stoke, Mark"
    },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Attachments

URL in the format
{RootUrl}/Projects/{ProjectID}/Organisations/{OrganisationID}/Attachments.

This returns the ActivityID of all the specified Organisation's Activities which
have attachments, along with the Attachment IDs.

This is to allow you to determine which Activities have attachments, without
having to iterate over each individual Activity.

The data is returned in the format

Property DataType ActivityId Int AttachmentIds Array of Int

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Successful

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/22/Attachments'

Example Response
200 OK
Body
Header(5)
View More

[
  {
    "activityID": 1079,
    "attachmentIDs": [
      1633
    ]
  },
  {
    "activityID": 1078,
    "attachmentIDs": [
      1631,

Contacts


DESCRIPTION

A Contact represents an individual with whom you have interacted with, or will
need to interact with in order to run your Project. For example a Contact could
be one or several of the following:

   
 * The manager of a company supplying you with materials for construction.
   
 * A local resident in the area affected by your Project.
   
 * A politician.
   

Contacts may be members of many Organisations, or no Organisations at all.

PROJECT SHARING

   
 * Contacts can be shared across Projects.
   
 * Certain properties can contain different values for each project. These
   properties are labelled as Project Specific in the below Schema.
   
 * You can specify the Projects the Contact is shared with using the Projects
   property.
   

It is possible that a Client may engage with the same Contact across different
Projects. For example the MP Joe Bloggs would be engaged with on any Projects
that are happening in their constituency. In this instance, the Client would add
"Joe Bloggs" once, and then share this Contact with any other Projects as and
when the engagement happens. When Contact are shared across multiple Projects,
there are some properties that store the same information across all Projects,
for example, First Name, Last Name, Address, Email, Telephone or Contact
Category and there are some properties that are assigned Project-specific
values. For example, Joe Bloggs may have a Contact Category of ‘MP’ (applied to
all projects), but in Project A they have an Influence of ‘High Influence / High
Interest’ and they are subscribed to receive the mailshots, but in Project B
they could be considered to be ‘Low Influence / Low Interest’ and be
unsubscribed from Mailshot communications.


SCHEMA

View More

Property DataType Required Restrictions Project Specific id Integer No (except
on update) None No firstName String No Maximum Length 256 characters No lastName
String Yes Maximum Length 256 characters No title Field No None No suffixes
Array of Fields No None No websiteUrl String No Maximum length 512 No email
String No Maximum Length 256 characters No telephone String No Maximum Length 50
characters No mobile String No Maximum Length 50 characters
Non-UK numbers require the relevant area code prefix as without a code all
entries will default to the UK area code (44) No positionHeld String No Maximum
Length 256 characters No email2 String No Maximum Length 256 characters No
telephone2 String No Maximum length 50 No linkedInUrl String No Maximum length
512 No twitterUrl String No Maximum length 512 No facebookUrl String No Maximum
length 512 No youtubeUrl String No Maximum length 512 No googlePlusUrl String No
Maximum length 512 No deputyName String No Maximum length 512 No
deputyPositionHeld String No Maximum length 256 No deputyEmail String No Maximum
length 256 No deputyTelephone String No Maximum length 50 No contactPermitted
Array of Fields No None No gender Field No None No employment Status Field No
None No influence Field No None Yes regions Array of Fields No None Yes
contactCategories Array of Fields No None No contactSubCategories Array of
Fields No None No projectCategories Array of Fields No None Yes
projectSubCategories Array of Fields No None Yes subProjects Array of Fields No
None Yes ethnicGroup Field No None No stakeholderCategories Field No None Yes
accountHandler Field No None Yes accountGroups Array of Field No None Yes
confidentialNotes String No None No mailshotSubscriptionPreference Subscription
Preference No (If no subscription preferences are specified, the subscription
preferences will default to the Project default preference instead of No
Response) None Yes postalSubscriptionPreference Subscription Preference No (If
no subscription preferences are specified, the subscription preferences will
default to the Project default preference instead of No Response) None Yes
telephoneSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes
smsSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes
eventSubscriptionPreference Subscription Preference No (If no subscription
preferences are specified, the subscription preferences will default to the
Project default preference instead of No Response) None Yes ageRange Field No
None No genderIdentityMatch Field No None Yes pregnancyStatus Field No None Yes
maritalStatus Field No None Yes disabled Field No None Yes disabilityTypes Array
of Field No None Yes otherDisabilityDescription String No None No
caringResponsibilities Array of Field No None Yes sexualOrientation Field No
None No department String No Maximum length 256 No ward Field No None No
constituency Field No None No genericPositionList Array of Field No None Yes
roleList Array of Field No None Yes yearOfBirth Integer No None No
preferredLanguage Field No None No religion Field No None No politicalParty
Field No None No interests Array of Field No None Yes distributionLists Array of
String No This property is read only. No notes String No None No quickNotes
String No None No organisationIDs Array of Integer No None No projects Array of
Project No None No


SUBSCRIPTION PREFERENCE

DESCRIPTION

The Subscription Preference data type represents a record of whether or not a
Contact has been asked if they would like to receive marketing communications,
and their answer.

SCHEMA

View More

Property Data Type Required Notes id Integer No **N.B.** Excluding the ID will
create a new Subscription Preference record.
Adding the ID, even on a PUT request will not create a new record, but will
instead keep the existing record.
createdDate String in the format
yyyy-MM-ddTHH:mm:ss e.g. 2019-02-20T17:17:20
Yes createdByText String Yes The name of individual submitting the preference
createdByURL String No If this preference has been updated through a website,
this is the URL of the page.
This information can only be added on a POST or PUT, and is not retreived on a
GET request. createdByIPAddress String No If this preference was created by an
HTTP request, this is the client IP address of that request.
This information can only be added on a POST or PUT, and is not retreived on a
GET request. createdByUserAgent String No If this preference was created by an
HTTP request, this is the User Agent address of that request.
This information can only be added on a POST or PUT, and is not retreived on a
GET request. status Field Yes method Field No -if the Status is "No Response",
otherwise Yes

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Activities


DESCRIPTION

Activities represent actions taken within the Tractivity system. Their purpose
is to record what has been done by Tractivity Users, Organisations or Contacts.
Activities can also be used to prompt Tractivity Users that action needs to be
taken with regards to specific Organisations, Contacts or Enquiries. These
actions can include:

   
 * A Contact requesting information about a project via a website.
   
 * An Email being sent in response to an Enquiry.
   
 * A Scheduled meeting with an Organisation.
   


SCHEMA

View More

Property DataType Required Restrictions id Integer No None title String Yes None
activitySubType Field Yes None status Field Yes None notes String No None
agreementNotes String No None ownerTeams Array of Field No (If no values
supplied, the Project's default team is used) None allocatedToTeams Array of
Field No (If no values supplied, the Project's default team is used) None
startDate String Yes yyyy-mm-dd endDate String Yes yyyy-mm-dd startTime String
No hh:mm:ss endTime String No hh:mm:ss stakeholderCategory Field No None
associatedOrganisationID Integer No None activityAmount Integer No None
subProject Field No None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Attachments

View More

Property Data Type Comments ID Int Filename string FileExtension string e.g.
".pdf" OriginalFilename string FileSize string Human readable description of
file size e.g. 2.3Mb or 530Kb FileAsByteArray array of byte This is only
populated if the IncludeData=main querystring parameter is included in the URL
FileSizeInBytes int Length of FileAsByteArray MimeType string

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Activities/1084/Attachments?pageIndex=0&pageSize=15

URL in the form
{BaseURL}/Projects/{ProjectID}/Contacts/{ContactID}/Activities/{ActivityID}/Attachments.

Returns a paged list of Attachments for the specified activity. These
attachments do not include the file data itself, just the metadata.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

Optional - the index of the page to return, starts at 0

pageSize
15

Optional - the maximum number of results to return in a single response. The
default & maximum is 15.



Successful, with paging parameters
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Activities/1084/Attachments?pageIndex=0&pageSize=15'

Example Response
200 OK
Body
Header(5)
View More

{
  "recordCount": 1,
  "pageCount": 1,
  "results": [
    {
      "id": 1636,
      "filename": "Spec Format_2014-04-14 doc version",
      "fileExtension": ".doc",
      "originalFilename": "Spec Format_2014-04-14 doc version",
      "fileSize": "261Kb",
      "fileAsByteArray": "",

GET

Get Attachment


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/36/Activities/1084/Attachments/1636?includeData=main

URL in the form
{BaseUrl}/Projects/{ProjectID}/Contacts/{ContactID}/Activities/{ActivityID}/Attachments/{AttachmentID}

If you include the querystring parameter includeData=main then the file data as
bytes will be returned. If not then only the meta data is returned.

This request is rate limited to:

   
 * once per second
   
 * 30 times per minute
   

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
includeData
main

Optional - if this parameter is included then the fileAsByteArray property is
populated.



Successful, with data
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/36/Activities/1084/Attachments/1636?includeData=main'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 1636,
  "filename": "Spec Format_2014-04-14 doc version",
  "fileExtension": ".doc",
  "originalFilename": "Spec Format_2014-04-14 doc version",
  "fileSize": "261Kb",
  "fileAsByteArray": "0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAAAAAAEAAAA+AEAAAAAAAAAEAAA+wEAAAEAAAD+////AAAAAPQBAAD1AQAA9gEAAPcBAAD////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////spcEAGQAJBAAA+BK/AAAAAAAAEAAAAAAACAAASQoAAA4AYmpiauD74PsAAAAAAAAAAAAAAAAAAAAAAAAJBBYAlEwBAIKRumeCkbpn7wEAAAAAAAA+AAAAAAAAAAAAAAAAAAAAAAAAABsAAAD//w8AAAAAAAAAAAD//w8AAAAAAAAAAAD//w8AAAAAAAAAAAAAAAAAAAAAALcAAAAAAPIMAAAAAAAA8gwAAIQaAAAAAAAAhBoAAAAAAAAcGwAAAAAAABwbAAAAAAAAHBsAABQAAAAAAAAAAAAAAP////8AAAAAMBsAAAAAAAAwGwAAAAAAADAbAAA4AAAAaBsAADQAAACcGwAAXAAAADAbAAAAAAAAiFEAAKoDAAD4GwAAAAAAAPgbAAAoAAAAIBwAAAAAAAAgHAAAAAAAACAcAAAAAAAAIzYAAAAAAAAjNgAAAAAAACM2AAAAAAAAB1EAAAIAAAAJUQAAAAAAAAlRAAAAAAAACVEAAAAAAAAJUQAAAAAAAAlR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

GET

Get all Activites for Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/61/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Activities"

This method fetches a paged list of all Activities for a Contact specified by
the ContactID within the Project specified by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
2

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Success - default paging
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1922,
      "associatedOrganisationID": 51,
      "title": "Catch-Up",
      "activitySubType": {
        "id": 1140,
        "title": "In Person"
      },

GET

Get Contact Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities/1922

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Activities/{ActivityID}"

Where the ProjectID is the ID of the Project to select data for, and the Contact
is the ID of the Contact the Activity is for and the ActivityID is the ID of the
Activity to select

Fetches a single Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities/1922'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1922,
  "associatedOrganisationID": 51,
  "title": "Catch-Up",
  "activitySubType": {
    "id": 1140,
    "title": "In Person"
  },
  "status": {
    "id": 1,
    "title": "Pending"

GET

Get Contact Activity fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Activities/Fields"

Where the ProjectID is the ID of the Project to select data for. The ContactID
is the ID of the Contact to select fields for.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Success - all field types
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
    "activityStatuses": [
        {
            "title": "Completed",
            "id": 2
        },
        {
            "title": "Pending",
            "id": 1
        }
    ],

PUT

Update Contact Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Activities".

Where the ContactID is the ID of the Contact to add an Activity to and the
ProjectID is the ID of the Project which the Contact belongs to.

The ID property of the Activity in the Request body specifies the Activity to
update.

All properties of the Activity are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the
Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 1931,
    "associatedOrganisationID": 51,
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {
            "title": "Completed",
            "id": 2



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1931,
    "associatedOrganisationID": 51,
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/61/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Activities".

Where the ContactID is the ID of the Contact to add an Activity to and the
ProjectID is the ID of the Project which the Contact belongs to.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "associatedOrganisationID": 51,
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"
    },



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "associatedOrganisationID": 51,
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1931,
  "associatedOrganisationID": 51,
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

Addresses


DESCRIPTION

An Address links a Contact to a Building The Address Entity holds any
information that is specific to that Contact’s relationship with a particular
building record, for example if the Contact is the owner or a tenant of the
building and when they began using the address. A Contact can have multiple
Addresses in the same Building and in seperate Buildings. You can record
previous Addresses by setting an Address as Detached.


PROJECT SHARING

If the Organisation is shared with a Project, then the Address & Building are
automatically shared with that Project.


SCHEMA

View More

Property DataType Required Restrictions id Integer No None unitNumber String No
Maximum length 128 building Building Yes Only the Building ID property is
required. relationship Field No None startDate String No yyyy-mm-hh detached
bool No None defaultAddress bool Yes None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get all Addresses for Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Addresses

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactId}/Addresses"

This method fetches a paged list of all Addresses for the Contact specified by
the ContactID in the Project specified by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0
pageSize
2


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "unitNumber": "Units 1-18",
      "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": {

GET

Get Contact Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/2069

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Addresses/{AddressID}"

Where the AddressID is the ID of the Address to select, the ContactID is the ID
of the Contact the Address is for and the ProjectID is the ID of the Project the
Contact is in.

Fetches a single Address.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/2069'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 2069,
  "unitNumber": "Units 1-18",
  "building": {
    "id": 2074,
    "postcode": "S9 1TL",
    "buildingNameNumberRoad": "Foundary Road",
    "locality": "The Mills",
    "town": {
      "id": 2,
      "title": "Sheffield"

GET

Get Contact Address fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Addresses/Fields"

Where the ProjectID is the ID of the Project to select data for. The ContactID
is the ID of the Contact to select Address fields for

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "relationships": [
    {
      "id": 3,
      "title": "Building Manager"
    },
    {
      "id": 1,
      "title": "Building Owner"
    },
    {

POST

Find Contact Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Duplicates

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Addresses/Duplicates".

Where the ProjectID is the ID of the Project to select data for, the ContactID
is the ID of the Contact to select date for.

This request will fetch all Addresses for the specified Contact where the
Address is for the same Building and the Address unitNumber contains the
unitNumber specified in the request body.


SCHEMA

View More

Property Required unitNumber Yes building.id Yes

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}



Success - Duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "1",
    "building": {
        "id": 2074
    }
}'

Example Response
200 OK
Body
Header(6)
View More

[
  {
    "id": 2069,
    "unitNumber": "Units 1-18",
    "building": {
      "id": 2074,
      "postcode": "S9 1TL",
      "buildingNameNumberRoad": "Foundary Road",
      "locality": "The Mills",
      "town": "Sheffield",
      "county": "South Yorkshire",

POST

Add Contact Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Addresses".

Where the ContactID is the ID of the Contact to add an Address to, and the
ProjectID is the ID of the Project the Contact is in.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
            "unitNumber": "Units 19-25",
            "building": {
                "id": 2074
            },
            "relationship": {
                "id": 1,
                "title": "Building Owner"
            },
            "startDate": "2019-02-20T00:00:00",
            "detached": false,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
            "unitNumber": "Units 19-25",
            "building": {
                "id": 2074
            },
            "relationship": {
                "id": 1,
                "title": "Building Owner"
            },

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2072,
  "unitNumber": "Units 19-25",
  "building": {
    "id": 2074,
    "postcode": "S9 1TL",
    "buildingNameNumberRoad": "Foundary Road",
    "locality": "The Mills",
    "town": {
      "id": 2,
      "title": "Sheffield"

PUT

Update Contact Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Addresses".

Where the ContactID is the ID of the Contact the Address being updated belongs
to. The ProjectID is the ID of the Project the Contact is In

The ID property of the Address in the Request body specifies the Address to
update.

All properties of the Address are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the Address

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 2072,
    "unitNumber": "Units 19-26",
    "building": {
        "id": 2074
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },
    "startDate": "2019-02-20T00:00:00",



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 2072,
    "unitNumber": "Units 19-26",
    "building": {
        "id": 2074
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"

Example Response
403 Forbidden
Body
Header(5)
No response body
This request doesn't return a response body

Enquiries


DESCRIPTION

An Enquiry represents a question or group of questions submitted by a Contact to
you regarding the Project you are running. All actions taken in response to
these questions are recorded within the Enquiry. The actions can include the
following:

   
 * Communicating with the Contact.
   
 * Referring questions onto an expert on the topic.
   

An Enquiry is always submitted by a Contact. A Contact can submit the Enquiry of
behalf of an Organisation, and in conjuction with other Contacts, but the
Enquiry is always stored directly against the Contact who personally submitted
the Enquiry.


SCHEMA

View More

Property DataType Required Restrictions id Integer On updates only None
contactId Integer Yes None title String Yes Maximum length 255
associatedOrganisationID Integer No None subProjects Array of Field No None
stakeholderCategory Field No None enquiryMadeVia Field No None receivedDate
DateTime No None accountHandler Field No None enquiryReason Field No None
enquiryFeedbackType Field No None notes String No None agreementNotes String No
None ownerTeams Array of Field No (if none provided, the Projects default Team
will be added). None type Field Yes None status Field Yes None consultationPhase
Field No None enquiry Categories Array of Field No None enquiryLocation Field No
None enquiryStage Field No None accountGroup Field No None sentiment Field No
None purposeOfEngagement String No None contactAddressIds Array ofInteger No
None enquiryResponseMethod Field No None enquiryStatusChangeDate DateTime No
None enquiryStageChangeDate DateTime No None enquiryAmount Integer No None
estimatedJobsCreated Decimal No None actualJobsCreated Decimal No None
estimatedJobsRelocated Decimal No None actualJobsRelocated Decimal No None
estimatedJobsSafeguarded Decimal No None actualJobsSafeguarded Decimal No None
estimatedCapitalExpenditure Decimal No None actualCapitalExpenditure Decimal No
None estimatedOutcomeSize Decimal No None actualOutcomeSize Decimal No None
enquiryPriority Field No None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Activities


DESCRIPTION

Activities represent actions taken within the Tractivity system. Their purpose
is to record what has been done by Tractivity Users, Organisations or Contacts.
Activities can also be used to prompt Tractivity Users that action needs to be
taken with regards to specific Organisations, Contacts or Enquiries. These
actions can include:

   
 * A Contact requesting information about a project via a website.
   
 * An Email being sent in response to an Enquiry.
   
 * A Scheduled meeting with an Organisation.
   


SCHEMA

View More

Property DataType Required Restrictions id Integer No None title String Yes None
activitySubType Field Yes None status Field Yes None notes String No None
agreementNotes String No None ownerTeams Array of Field No (If no values
supplied, the Project's default team is used) None allocatedToTeams Array of
Field No (If no values supplied, the Project's default team is used) None
startDate String Yes yyyy-mm-dd endDate String Yes yyyy-mm-dd startTime String
No hh:mm:ss endTime String No hh:mm:ss stakeholderCategory Field No None
associatedContactIDs Array of Int No None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Attachments

View More

Property Data Type Comments ID Int Filename string FileExtension string e.g.
".pdf" OriginalFilename string FileSize string Human readable description of
file size e.g. 2.3Mb or 530Kb FileAsByteArray array of byte This is only
populated if the IncludeData=main querystring parameter is included in the URL
FileSizeInBytes int Length of FileAsByteArray MimeType string

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Enquiries/83/Activities/702/Attachments?pageIndex=0&pageSize=15

URL in the form
{BaseURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities/{ActivityID}/Attachments.

Returns a paged list of Attachments for the specified activity. These
attachments do not include the file data itself, just the metadata.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

Optional - the index of the page to return, starts at 0

pageSize
15

Optional - the maximum number of results to return in a single response. The
default & maximum is 15.



Successful, with paging parameters
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Enquiries/83/Activities/702/Attachments?pageIndex=1&pageSize=2'

Example Response
200 OK
Body
Header(5)
View More

{
  "recordCount": 3,
  "pageCount": 2,
  "results": [
    {
      "id": 1639,
      "filename": "Media1",
      "fileExtension": ".mp4",
      "originalFilename": "Media1",
      "fileSize": "1Mb",
      "fileAsByteArray": "",

GET

Get Attachment


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Enquiries/83/Activities/702/Attachments/1638?includeData=main

URL in the form
{BaseUrl}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries/{EnquiryID}/Activities/{ActivityID}/Attachments/{AttachmentID}

If you include the querystring parameter includeData=main then the file data as
bytes will be returned. If not then only the meta data is returned.

This request is rate limited to:

   
 * once per second
   
 * 30 times per minute
   

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
includeData
main

Optional - if this parameter is included then the fileAsByteArray property is
populated.



Successful, metadata only
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Enquiries/83/Activities/702/Attachments/1638'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 1638,
  "filename": "Presentation1",
  "fileExtension": ".pptx",
  "originalFilename": "Presentation1",
  "fileSize": "31Kb",
  "fileAsByteArray": "",
  "fileSizeInBytes": 31756,
  "mimeType": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
}

GET

Get all Enquiry Activities


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities?

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries/{EnquiryID}/Activities"

This method fetches a paged list of all Activities for an Enquiry with the ID
specified in EnquiryID. The ContactID is the ID of the Contact who submitted the
Enquiry. The ProjectID is the ID of the Project the Contact, Enquiry and
Activity is in.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0
pageSize
5


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1928,
      "associatedContactIDs": [
        115
      ],
      "title": "Meeting Scheduled",
      "activitySubType": {
        "id": -3,

GET

Get Enquiry Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities/1928

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries/{EnquiryID}/Activities/{ActivityID}"

This method fetches an Activity with the ID specified by ActivityID. The
Activity is for an Enquiry with the ID specified in EnquiryID. The ContactID is
the ID of the Contact who submitted the Enquiry. The ProjectID is the ID of the
Project the Contact, Enquiry and Activity is in.

Fetches a single Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities/1928'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1928,
  "associatedContactIDs": [
    115
  ],
  "title": "Meeting Scheduled",
  "activitySubType": {
    "id": -3,
    "title": "Meeting"
  },
  "status": {

GET

Get Enquiry Activity Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries/{EnquiryID}/Activities/Fields".

Where the EnquiryID is the ID of the Enquiry to select Activity Fields for. The
ContactID is the ID of the Contact who submitted the Enquiry. The ProjectID is
the ID of the Project the Contact, Enquiry and Activity is in.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

POST

Add Enquiry Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiry/{EnquiryID}/Activities".

Where the EnquiryID is the ID of the Enquiry the Activity is to be added to. The
ContactID is the ID of the Contact who submitted the Enquiry. The ProjectID is
the ID of the Project the Contact, Enquiry and Activity is in.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"
    },
    "notes": "call about last meeting",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1932,
  "associatedContactIDs": [],
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

PUT

Update Enquiry Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries/{EnquiryID}/Activities".

Where the EnquiryID is the ID of the Enquiry the Activity being updated belongs
to. The ContactID is the ID of the Contact who submitted the Enquiry. The
ProjectID is the ID of the Project the Contact, Enquiry and Activity is in.

The ID property of the Activity in the Request body specifies the Activity to
update.

All properties of the Activity are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the
Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 1932,
    "associatedContactIDs": [],
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {
        "id": 1,
        "title": "Pending"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1932,
    "associatedContactIDs": [],
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
GET

Get all Enquiries for Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries?

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries"

This method fetches a paged list of all Enquiries for a Contact specified by the
ContactID, in the Project specified by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0
pageSize
5


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1031,
      "title": "Concern over proximity of site to airport",
      "contactID": 115,
      "associatedOrganisationID": 52,
      "subProjects": [
        {
          "id": 226,

GET

Get Enquiry


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries"

Where the ContactID is the ID of the Contact to fetch Enquiries for and the
ProjectID is the ID of the Project the Contact is in.

Fetches a single Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1031,
  "title": "Concern over proximity of site to airport",
  "contactID": 115,
  "associatedOrganisationID": 52,
  "subProjects": [
    {
      "id": 226,
      "title": "Construction"
    }
  ],

GET

Get Enquiry fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries/Fields?

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Fields"

Where the ContactID is the ID of the Contact to fetch Enquiry Fields for and the
ProjectID is the ID of the Project the Contact is in.

Fetches the Enquiry Fields which are available for this Contact in this Project.

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
accountHandlers
include
madeVia
include
statuses


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "subProjects": [
    {
      "id": 226,
      "title": "Construction"
    },
    {
      "id": 227,
      "title": "Land clearing"
    }
  ],

POST

Add Enquiry


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries".

Where the ContactID is the ID of the Contact to add the Enquiry to and the
ProjectID is the ID of the Project the Contact is in.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Request for information",
    "associatedOrganisationID": 53,
    "subProjects": [
        {
            "id": 226,
            "title": "Construction"
        }
    ],
    "stakeholderCategory":  {
            "id": 4,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Request for information",
    "associatedOrganisationID": 53,
    "subProjects": [
        {
            "id": 226,
            "title": "Construction"
        }
    ],

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1032,
  "title": "Request for information",
  "contactID": 117,
  "associatedOrganisationID": 53,
  "subProjects": [
    {
      "id": 226,
      "title": "Construction"
    }
  ],

PUT

Update Enquiry


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries/

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries".

Where the ContactID is the ID of the Contact the Enquiry being updated belongs
to, and the ProjectID is the ID of the Project the Contact belongs to.

The ID property of the Enquiry in the Request body specifies the Building to
update.

All properties of the Enquiry are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the Enquiry

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
	"id": 117,
    "title": "Request for information",
    "contactID": 117,
    "associatedOrganisationID": 53,
    "subProjects": [
        {
            "id": 226,
            "title": "Construction"
        }
    ],



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Request for information",
    "contactID": 117,
    "associatedOrganisationID": 53,
    "subProjects": [
        {
            "id": 226,
            "title": "Construction"
        }

Example Response
400 Bad Request
Body
Header(6)

{
  "message": "The request is invalid.",
  "modelState": {
    "dto.Type": [
      "The Type field is required."
    ]
  }
}

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Enquiries/83/Attachments

URL in the format
{RootUrl}/Projects/{ProjectID}/Contacts/{ContactID}/Enquiries/{EnquiryID}/Attachments.

This returns the ActivityID of all the specified Enquiry's Activities which have
attachments, along with the Attachment IDs.

This is to allow you to determine which Activities have attachments, without
having to iterate over each individual Activity.

The data is returned in the format

Property DataType ActivityId Int AttachmentIds Array of Int

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Successful

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Enquiries/83/Attachments'

Example Response
200 OK
Body
Header(5)
View More

[
  {
    "activityID": 703,
    "attachmentIDs": [
      1637
    ]
  },
  {
    "activityID": 702,
    "attachmentIDs": [
      843

GET

Get all Contacts for Project


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts?pageIndex=0&pageSize=15&

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Contacts"

This method fetches a paged list of all Contacts within the Project specified by
the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
15

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request




Success, with paging parameters
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts?pageIndex=1&pageSize=1'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 2,
  "results": [
    {
      "id": 115,
      "firstName": "Paul",
      "lastName": "Flyer",
      "suffixes": [],
      "email": "paul.flyer@flydsa.com",
      "telephone": "",
      "mobile": "447865412565",

GET

Get Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/2761

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/{ContactID}"

Where the ProjectID is the ID of the Project to select data for, and the
ContactID is the ID of the Contact to select

Fetches a single Contact.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 115,
  "firstName": "Paul",
  "lastName": "Flyer",
  "suffixes": [],
  "email": "paul.flyer@flydsa.com",
  "telephone": "",
  "mobile": "447865412565",
  "positionHeld": "",
  "telephone2": "",
  "email2": "",

GET

Get Contact fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Contact/Fields"

Where the ProjectID is the ID of the Project to select data for.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Contact are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
contactPermissions

[Optional] The name of a Field type to return the Fields for

include
employmentStatuses

[Optional] The name of a Field type to return the Fields for



Success - specific fields
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=contactPermissions&include=employmentStatuses'

Example Response
200 OK
Body
Header(6)
View More

{
  "titles": [],
  "suffixes": [],
  "contactPermissions": [
    {
      "id": -1,
      "title": "Email"
    },
    {
      "id": -2,
      "title": "Post"

POST

Find Contact duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Contacts/Duplicates". Where the ProjectID is the
ID of the Project to select data for.

This request will Fetch all Contacts in the Project whose firstName, lastName,
and email address contain the supplied values.


SCHEMA

View More

Property Required firstname No lastName No email No portalPassword No

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "lastName": "Northern"
}



Success - Duplicates Found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName": "Joseph",
    "lastName": "Northern",
    "email": "j.northern@sheffieldwindturbines.com"
}'

Example Response
200 OK
Body
Header(6)
View More

[
  {
    "id": 114,
    "title": {
      "id": 5,
      "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],
    "email": "j.northern@sheffieldwindturbines.com",

POST

Add Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Contacts".
Where the ProjectID is the ID of the Project to add a Contact to.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "firstName": "John",
    "lastName": "Doe",
    "suffixes": [],
    "email": "john.doe@tractivity.co.uk",
    "portalPassword": "bAVn8QtxzECmFD",
    "telephone": "01629 815654",
    "positionHeld": "Head Of Development",
    "contactPermitted": [
        {
            "id": -1,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName": "John",
    "lastName": "Smith",
    "suffixes": [],
    "email": "john.smith@tractivity.co.uk",
    "telephone": "01629 815654",
    "positionHeld": "Head of Development",
    "contactPermitted": [
        {

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 120,
  "firstName": "John",
  "lastName": "Smith",
  "suffixes": [],
  "email": "john.smith@tractivity.co.uk",
  "telephone": "01629 815654",
  "positionHeld": "Head of Development",
  "contactPermitted": [
    {
      "id": -1,

PUT

Update Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Contacts".
Where the ProjectID is the ID of the Project to update a Building in.

The ID property of the Contact in the Request body specifies the Building to
update.

All properties of the Contact are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the Contact

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
  "id": 3238,
  "firstName": "John",
  "lastName": "Doe",
  "suffixes": [],
  "email": "john.doe@tractivity.co.uk",
  "portalLastLoginDate": "2019-10-25T09:04:05.513",
  "telephone": "01629 815654",
  "positionHeld": "Head Of Development",
  "linkedInUrl": "",
  "twitterUrl": "",



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 117,
    "firstName": "John",
    "lastName": "Smith",
    "suffixes": [],
    "email": "john.smith@tractivity.co.uk",
    "telephone": "01629 815654",
    "mobile":"07845657146",
    "positionHeld": "Head of Development",

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Attachments

URL in the format
{RootUrl}/Projects/{ProjectID}/Contacts/{ContactID}/Attachments.

This returns the ActivityID of all the specified Contact's Activities which have
attachments, along with the Attachment IDs.

This is to allow you to determine which Activities have attachments, without
having to iterate over each individual Activity.

The data is returned in the format

Property DataType ActivityId Int AttachmentIds Array of Int

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Successful

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Attachments'

Example Response
200 OK
Body
Header(5)
View More

[
  {
    "activityID": 1084,
    "attachmentIDs": [
      1636
    ]
  },
  {
    "activityID": 361,
    "attachmentIDs": [
      495

Enquiries


DESCRIPTION

An Enquiry represents a question or group of questions submitted by a Contact to
you regarding the Project you are running. All actions taken in response to
these questions are recorded within the Enquiry. The actions can include the
following:

   
 * Communicating with the Contact.
   
 * Referring questions onto an expert on the topic.
   

An Enquiry is always submitted by a Contact. A Contact can submit the Enquiry of
behalf of an Organisation, and in conjuction with other Contacts, but the
Enquiry is always stored directly against the Contact who personally submitted
the Enquiry.


SCHEMA

View More

Property DataType Required Restrictions id Integer On updates only None
contactId Integer Yes None title String Yes Maximum length 255
associatedOrganisationID Integer No None subProjects Array of Field No None
stakeholderCategory Field No None enquiryMadeVia Field No None receivedDate
DateTime No None accountHandler Field No None enquiryReason Field No None
enquiryFeedbackType Field No None notes String No None agreementNotes String No
None ownerTeams Array of Field No (if none provided, the Projects default Team
will be added). None type Field Yes None status Field Yes None consultationPhase
Field No None enquiry Categories Array of Field No None enquiry Location Field
No None sentiment Field No None purposeOfEngagement String No None
contactAddressIds Array ofInteger No None enquiryResponseMethod Field No None
enquiryAmount Integer No None enquiryStage Field No None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Activities


DESCRIPTION

Activities represent actions taken within the Tractivity system. Their purpose
is to record what has been done by Tractivity Users, Organisations or Contacts.
Activities can also be used to prompt Tractivity Users that action needs to be
taken with regards to specific Organisations, Contacts or Enquiries. These
actions can include:

   
 * A Contact requesting information about a project via a website.
   
 * An Email being sent in response to an Enquiry.
   
 * A Scheduled meeting with an Organisation.
   


SCHEMA

View More

Property DataType Required Restrictions id Integer No None title String Yes None
activitySubType Field Yes None status Field Yes None notes String No None
agreementNotes String No None ownerTeams Array of Field No (If no values
supplied, the Project's default team is used) None allocatedToTeams Array of
Field No (If no values supplied, the Project's default team is used) None
startDate String Yes yyyy-mm-dd endDate String Yes yyyy-mm-dd startTime String
No hh:mm:ss endTime String No hh:mm:ss stakeholderCategory Field No None
associatedContactIDs Array of Int No None activityAmount Integer No None
emailContent string No Will accept HTML but potentially dangerous content will
be stripped.
Please validate that no dnagerous content like script is submitted.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Attachments

View More

Property Data Type Comments ID Int Filename string FileExtension string e.g.
".pdf" OriginalFilename string FileSize string Human readable description of
file size e.g. 2.3Mb or 530Kb FileAsByteArray array of byte This is only
populated if the IncludeData=main querystring parameter is included in the URL
FileSizeInBytes int Length of FileAsByteArray MimeType string

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/83/Activities/702/Attachments?pageIndex=0&pageSize=15

URL in the form
{BaseURL}/Projects/{ProjectID}/Enquiry/{EnquiryID}/Activities/{ActivityID}/Attachments.

Returns a paged list of Attachments for the specified activity. These
attachments do not include the file data itself, just the metadata.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

Optional - the index of the page to return, starts at 0

pageSize
15

Optional - the maximum number of results to return in a single response. The
default & maximum is 15.



Example Request
Successful, with paging parameters

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/83/Activities/702/Attachments?pageIndex=0&pageSize=15'

Example Response
200 OK
Body
Header(5)
View More

{
  "recordCount": 3,
  "pageCount": 1,
  "results": [
    {
      "id": 843,
      "filename": "Version 6.1",
      "fileExtension": ".pdf",
      "originalFilename": "Version 6.1",
      "fileSize": "178Kb",
      "fileAsByteArray": "",

GET

Get Attachment


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/83/Activities/702/Attachments/843?includeData=main

URL in the form
{BaseUrl}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities/{ActivityID}/Attachments/{AttachmentID}

If you include the querystring parameter includeData=main then the file data as
bytes will be returned. If not then only the meta data is returned.

This request is rate limited to:

   
 * once per second
   
 * 30 times per minute
   

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
includeData
main

Optional - if this parameter is included then the fileAsByteArray property is
populated.



Successful, with data
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/83/Activities/702/Attachments/1638?includeData=main'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 1638,
  "filename": "Presentation1",
  "fileExtension": ".pptx",
  "originalFilename": "Presentation1",
  "fileSize": "31Kb",
  "fileAsByteArray": "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

GET

Get all Activities for Enquiry


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities"

This method fetches a paged list of all Activities for an Enquiry with the ID
specified in EnquiryID. The ProjectID is the ID of the Project the Contact,
Enquiry and Activity is in.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031/Activities'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1932,
      "associatedContactIDs": [],
      "title": "Phone call",
      "activitySubType": {
        "id": -4,
        "title": "Phone Call"
      },

GET

Get Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031/Activities/1932

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities/{ActivityID}"

This method fetches an Activity with the ID specified by ActivityID. The
Activity is for an Enquiry with the ID specified in EnquiryID. The ProjectID is
the ID of the Project the Contact, Enquiry and Activity is in.

Fetches a single Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031/Activities/1932'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1932,
  "associatedContactIDs": [],
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

GET

Get Enquiry Activity fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031/Activities/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities/Fields".

Where the EnquiryID is the ID of the Enquiry to select Activity Fields for. The
ProjectID is the ID of the Project the Contact, Enquiry and Activity is in.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success - all fields

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031/Activities/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

POST

Add Enquiry Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/115/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiry/{EnquiryID}/Activities".

Where the EnquiryID is the ID of the Enquiry the Activity is to be added to. The
ProjectID is the ID of the Project the Contact, Enquiry and Activity is in.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"
    },
    "notes": "call about last meeting",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/115/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1933,
  "associatedContactIDs": [],
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

PUT

Update Enquiry Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/115/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities".

Where the EnquiryID is the ID of the Enquiry the Activity being updated belongs
to. The ProjectID is the ID of the Project the Contact, Enquiry and Activity is
in.

The ID property of the Activity in the Request body specifies the Activity to
update.

All properties of the Activity are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the
Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 1933,
    "associatedContactIDs": [],
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {
        "id": 1,
        "title": "Pending"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/115/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1933,
    "associatedContactIDs": [],
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
GET

Get all Enquiries for Project


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries?pageIndex=0&pageSize=15

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Enquiries"

This method fetches a paged list of all Enquiries within the Project specified
by the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
15

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Example Request
Success - 1st page of results

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1031,
      "title": "Concern over proximity of site to airport",
      "contactID": 115,
      "associatedOrganisationID": 52,
      "subProjects": [
        {
          "id": 226,

GET

Get Enquiry


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/117

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}".

Where the ProjectID is the ID of the Project to select data for, and the
EnquiryID is the ID of the Enquiry to select

Fetches a single Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/1031'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1031,
  "title": "Concern over proximity of site to airport",
  "contactID": 115,
  "associatedOrganisationID": 52,
  "subProjects": [
    {
      "id": 226,
      "title": "Construction"
    }
  ],

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/83/Attachments

URL in the format
{RootUrl}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Attachments.

This returns the ActivityID of all the specified Enquiry's Activities which have
attachments, along with the Attachment IDs.

This is to allow you to determine which Activities have attachments, without
having to iterate over each individual Activity.

The data is returned in the format

Property DataType ActivityId Int AttachmentIds Array of Int

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Successful

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/83/Attachments'

Example Response
200 OK
Body
Header(5)
View More

[
  {
    "activityID": 703,
    "attachmentIDs": [
      1637
    ]
  },
  {
    "activityID": 702,
    "attachmentIDs": [
      843,

Batch

The batch section contains requests designed to increase performance by
performing the work of several requests in one request.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

PUT

Organisation, Contact & Address


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/OrganisationContactAddress


DESCRIPTION

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Batch/OrganisationContactAddress".

This request will allow you to submit a Contact, Organisation and an Address,
automatically performing duplication checks across multiple Projects and either
Adding or Updating the entities as appropriate and sharing the entities across
projects. Duplication checks are

REQUIRED DATA

This method requires a Contact or an Organisation or both.
The Address is optional, however if an Address is supplied it must have a
property 'building' of type Building
You must supply either the projects property with at least one Project

RELATIONSHIPS

If a Contact and an Organisation is supplied then the Contact is associated to
that Organisation.
If a Property and an Address is supplied as well as a Contact then the Address
is added to the Contact.
If a Property and an Address is supplied as well as an Organisation the the
Address is added to the Organisation.

DUPLICATION CHECKS

If a Contact with the same Lastname and Email address if found in an available
Project then instead of adding an additional Contact that Contact is updated
with that information.
If an Organisation with the same Name if found in an available Project then
instead of adding an additional Organisation that Organisation is updated with
that information.
If a Building with the same Postcode and buildingNameNumberRoad is found in an
available Project that that is updated instead of adding a new Building.
If an Address if found linking the same Organisation to the same Building then
that address is updated instead of adding an additional Organisation Address.
If an Address if found linking the same Contact to the same Building then that
address is updated instead of adding an additional Contact Address.

DUPLICATION UPDATE MECHANISM (OVERWRITEALLDATA)

If a duplicate entity is found then that entity is updated. By default this
update will merge properties, preserving the data on the exisiting entity where
a conflict occurs. So for example, if a duplicate contact is found the following
would occur:

View More

Property Data Type Existing Value Submitted Value Result positionHeld String (no
value) Developer Developer firstName String Arthur (no value) Arthur telephone
String 01629 815914 0151 254678 01629 815914 stakeholderCategories Field (no
value) Statutory Statutory accountHandler Field Joe Bloggs Mary Biggs Joe Bloggs
contactCategories Array of Fields Category A
Category B Category B
Category C Category A
Category B
Category C

However if the property overwriteData is set to true in the request body then
the following would be occur:

View More

Property Data Type Existing Value Submitted Value Result positionHeld String (no
value) Developer Developer firstName String Arthur (no value) (no value)
telephone String 01629 815914 0151 254678 0151 254678 stakeholderCategories
Field (no value) Statutory Statutory accountHandler Field Joe Bloggs Mary Biggs
Mary Biggs contactCategories Array of Fields Category A
Category B Category B
Category C Category A
Category B

PROJECTS

This data will be added to the project specified in the {ProjectID} segment of
the request URL. By default the duplication check is performed only the Project
specified by the {ProjectID} in the URL. However duplication checks can be
performed across multiple Projects. If a duplicate is found in a different
Project then that duplicate is shared with the Project specified by the
{ProjectID} in the URL. You can specify which Projects to perform a duplication
check across by listing their IDs in the 'projects' array in the request body.

If set to true and a matching Address/Contact/Organisation is found in the
duplication check, all of that duplicates's data is overwritten

SCHEMA

View More

Property Data Type Required Notes projects Array of Project Yes

        </td>
        <td>
            This specifies the projects that the request should validate to.
        </td>
    </tr>
    <tr>
        <td>
            contact
        </td>
        <td>
            <a href="#b100abf7-cc80-4dd2-9d5b-d0920311f356">Contact</a>
        </td>
        <td>
            Yes (unless an Organisation has been provided)
        </td>
        <td>
        </td>
    </tr>
    <tr>
        <td>
                organisation
            </td>
            <td>
                <a href="#bf0963eb-9495-4127-a15c-9320958c91f9">Organisation</a>
            </td>
            <td>
                Yes (unless a Contact has been provided)
            </td>
            <td>
            </td>
        </tr>
        <tr>
            <td>
                Address
            </td>
            <td>
                <a href="#02a9d71d-eb91-4db8-9c22-51cbdef5813a">Address</a> with a <a href="#02600376-039f-40f2-ac5c-e771be6ab72d"> Building </a> property
            </td>
            <td>
                No
            </td>
            <td>
                This specifies the Address for the any Contact or Company in this request.
                <br /> Please note that the Contact Address and Organisation Address object share the same schema.
            </td>
        </tr>

organisationDistributionListIDs Array of Integers No This specifies any
Distribution Lists the Organisation is to be added to.
Please note that if the specified Distribution List format is postal the Address
entity is also required. ContactDistributionListIDs Array of Integers No This
specifies any Distribution Lists the Organisation is to be added to.
Please note that if the specified Distribution List format is postal the Address
entity is also required. overwriteData Boolean No Defaults to False.


AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
	"Organisation": {
		"name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,
        "name": "Stoke, Mark"
    },



Example Request
Organisation & Contact & Address success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/OrganisationContactAddress' \
--header 'Content-Type: application/json' \
--data-raw '{
	"Organisation": {
		"name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,

Example Response
200 OK
Body
Header(6)
View More

{
  "projects": [
    {
      "id": 21,
      "title": "Default Org"
    }
  ],
  "contact": {
    "id": 2848,
    "title": {
      "id": 5,

POST

Get Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Batch/Fields".

Where ProjectID is the ID of the Project used to select fields.

This method is used to select the Fields for multiple Entities at once to
increase performance.

View More

Property Data Type Notes contactFieldsToInclude Array of String This specifies
the names of Field types to fetch. enquiryFieldsToInclude Array of String This
specifies the names of Field types to fetch. organisationFieldsToInclude Array
of String This specifies the names of Field types to fetch.
activityFieldsToInclude Array of String This specifies the names of Field types
to fetch. buildingFieldsToInclude Array of String This specifies the names of
Field types to fetch. addressFieldsToInclude Array of String This specifies the
names of Field types to fetch.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
        "stakeholdercategories"
    ],
    "enquiryFieldsToInclude": [
        "madeVia",
        "accountHandler"
    ],
    "organisationFieldsToInclude": [
        "categories",
        "subcategories"



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
	"contactFieldsToInclude":["stakeholdercategories"],
	"enquiryFieldsToInclude":["madeVia","accountHandler"],
	"organisationFieldsToInclude":["categories","subcategories"],
	"activityFieldsToInclude":["statuses"],
	"buildingFieldsToInclude":["counties"]
}'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityFields": {
    "statuses": [
      {
        "id": 2,
        "title": "Completed"
      },
      {
        "id": 1,
        "title": "Pending"
      }

Events


DESCRIPTION

An Event represents a planned public or social occasion with a group of Contacts
regarding the Project you are running.

Please note that if the Event property isDisplayedOnWebsite has not been set to
true, then this Event is not meant to be publically available.

Certain endpoints only return a minimal subset of these properties for
performance reasons. These properties are specified in the below table.


SCHEMA

View More

Property DataType Required Restrictions & Notes Available in minimal id Integer
No None Yes title string yes Max length 100 characters Yes eventStartDateTime
DateTime Yes Format yyyy-dd-mmThh:mm:ss e.g. 2019-02-25T12:00:00 Yes
eventEndDateTime DateTime Yes Format yyyy-dd-mmThh:mm:ss e.g.
2019-02-25T12:00:00 Yes eventOverview String No Maximum Length 512 characters
This is a brief description of the Event Yes eventInformation string (HTML) No
Maximum Length 512 characters
This is a complete description of the Event, more detailed that eventOverview
Please note that this content is HTML, you may need to parse or filter the
content before rendering it in a browser. No allowRegistration True/False Yes
None Yes isDisplayedOnWebsite True/False Yes No restrictions.
**If this is set to False, do not display the event publicly** Yes eventCategory
Field No None Yes eventThemes Array of Field No None Yes eventSubProjects Array
of Field No None Yes eventStatus Field yes No restrictions. Yes eventType Field
yes No restrictions. Yes venue string No Maximum Length 100 characters Yes

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Invited Contacts


DESCRIPTION

A Contact can be registered to an event with a given invitation status.


SCHEMA

View More

Property DataType Required Restrictions & Notes Id Integer No None
The Id of the Invitation itself. contactId Integer Yes None
The Id of the Contact who has been/will be invited. eventId Integer No None
The Id of the Event the Contact has been/will be invited to attend.
invitationStatus Field Yes None eventAttended Boolean (true/false)
Defaults to false. No None
Indicates whether or not the Contact attended the Event.
It is possible for a Contact to attend an Event even if they were not sent an
invitation.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Add Invited Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/57/InvitedContacts

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Events/{EventID}/InvitedContacts".

Where the ProjectID is the ID of the Project and EventID is the ID of the event
you are wanting to add the Contact to.

You cannot invite the same Contact to the same Event more than once. If you
attempt to do so you will receive a 400 response.

If you attempt to invite a Contact to an Event which is already at capacity you
will receive a 400 response.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "ContactId": 2792,
    "eventAttended":"true",
    "InvitationStatus": {
        "id": 6
    }
}



Add Invited Contact as attended without invitation
Example Request
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/57/InvitedContacts' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ContactId": 2792,
    "eventAttended":"true",
    "InvitationStatus": {
        "id": 6
    }
}'

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 169,
  "contactId": 2792,
  "eventId": 57,
  "invitationStatus": {
    "id": 6
  },
  "eventAttended": true,
  "project": {
    "id": 48
  }

GET

Get Invited Contact Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/26/InvitedContacts/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Events/{EventID}/InvitedContacts/Fields"

Where the ProjectID is the ID of the Project to select data for and EventID is
the ID of the event.

Fetches the Fields which are available for this Event Registration.

If no query string parameters are specified in the URL then all Field types for
Event Registration are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
eventInvitationStatuses

[Optional] The name of a Field type to return the Fields for



Example Request
Get Event Registration Fields

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/26/InvitedContacts/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "eventInvitationStatuses": [
    {
      "id": 3,
      "title": "Awaiting Confirmation"
    },
    {
      "id": 4,
      "title": "Awaiting Invitation"
    },
    {

GET

Get Invited Contact


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/56/InvitedContacts/166

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Events/{EventID}/InvitedContacts/{EventInvitationID}"

Where the ProjectID is the ID of the Project to select data for, the EventID is
the ID of the Event and the EventInvitationID is the ID of the Invitation.

Fetches a single Event Invitation.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get Invited Contact

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/56/InvitedContacts/166'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 166,
  "contactId": 2792,
  "eventId": 56,
  "invitationStatus": {
    "id": 4,
    "title": "Awaiting Invitation"
  },
  "eventAttended": false,
  "project": {
    "id": 48,

Activities


DESCRIPTION

Activities represent actions taken within the Tractivity system. Their purpose
is to record what has been done by Tractivity Users, Organisations or Contacts.
Activities can also be used to prompt Tractivity Users that action needs to be
taken with regards to specific Organisations, Contacts, Enquiries and Events.
These actions can include:

   
 * A Contact requesting information about a project via a website.
   
 * An Email being sent in response to an Enquiry.
   
 * A Scheduled meeting with an Organisation.
   


SCHEMA

View More

Property DataType Required Restrictions id Integer No None title String Yes None
activitySubType Field Yes None status Field Yes None notes String No None
agreementNotes String No None ownerTeams Array of Field No (If no values
supplied, the Project's default team is used) None allocatedToTeams Array of
Field No (If no values supplied, the Project's default team is used) None
startDate String Yes yyyy-mm-dd endDate String Yes yyyy-mm-dd startTime String
No hh:mm:ss endTime String No hh:mm:ss stakeholderCategory Field No None
associatedContactIDs Array of Int No None activityAmount Integer No None
emailContent string No Will accept HTML but potentially dangerous content will
be stripped.
Please validate that no dangerous content like script is submitted.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Attachments

View More

Property Data Type Comments ID Int Filename string FileExtension string e.g.
".pdf" OriginalFilename string FileSize string Human readable description of
file size e.g. 2.3Mb or 530Kb FileAsByteArray array of byte This is only
populated if the IncludeData=main querystring parameter is included in the URL
FileSizeInBytes int Length of FileAsByteArray MimeType string

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities/1001/Attachments?pageIndex=0&pageSize=15

URL in the form
{BaseURL}/Projects/{ProjectID}/Events/{EventID}/Activities/{ActivityID}/Attachments.

Returns a paged list of Attachments for the specified activity. These
attachments do not include the file data itself, just the metadata.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

Optional - the index of the page to return, starts at 0.

pageSize
15

Optional - the maximum number of results to return in a single response. The
default & maximum is 15.



Example Request
Sucessful, with paging parameters

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities/1001/Attachments?pageIndex=0&pageSize=15'

Example Response
200 OK
Body
Header(5)
View More

{
  "recordCount": 1,
  "pageCount": 1,
  "results": [
    {
      "id": 1267,
      "filename": "TRac Logo",
      "fileExtension": ".jpg",
      "originalFilename": "TRac Logo.jpg",
      "fileSize": "6Kb",
      "fileAsByteArray": "",

GET

Get Attachment


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities/1001/Attachments/1267

URL in the form
{BaseUrl}/Projects/{ProjectID}/Events/{EventID}/Activities/{ActivityID}/Attachments/{AttachmentID}

If you include the querystring parameter includeData=main then the file data as
bytes will be returned. If not then only the meta data is returned.

This request is rate limited to:

   
 * once per second
   
 * 30 times per minute
   

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
includeData
main

Optional - if this parameter is included then the fileAsByteArray property is
populated.



Sucessful, with data
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities/1001/Attachments/1267?includeData=main'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 1267,
  "filename": "TRac Logo",
  "fileExtension": ".jpg",
  "originalFilename": "TRac Logo.jpg",
  "fileSize": "6Kb",
  "fileAsByteArray": "/9j/4AAQSkZJRgABAQEAYABgAAD/4QBoRXhpZgAATU0AKgAAAAgABAEaAAUAAAABAAAAPgEbAAUAAAABAAAARgEoAAMAAAABAAIAAAExAAIAAAARAAAATgAAAAAAAABgAAAAAQAAAGAAAAABcGFpbnQubmV0IDQuMi4xMwAA/9sAQwACAQEBAQECAQEBAgICAgIEAwICAgIFBAQDBAYFBgYGBQYGBgcJCAYHCQcGBggLCAkKCgoKCgYICwwLCgwJCgoK/9sAQwECAgICAgIFAwMFCgcGBwoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoK/8AAEQgAcgDTAwEhAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/EAB8BAAMBAQEBAQEBAQEAAAAAAAABAgMEBQYHCAkKC//EALURAAIBAgQEAwQHBQQEAAECdwABAgMRBAUhMQYSQVEHYXETIjKBCBRCkaGxwQkjM1LwFWJy0QoWJDThJfEXGBkaJicoKSo1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoKDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uLj5OXm5+jp6vLz9PX29/j5+v/aAAwDAQACEQMRAD8A/fyigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKKACigAooAKp+IfEGieEvD994q8Tarb2Om6ZZy3eoX11KI4re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

GET

Get all Activities for Event


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities"

This method fetches a paged list of all Activities for an Enquiry with the ID
specified in EnquiryID. The ProjectID is the ID of the Project the Contact,
Enquiry and Activity is in.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/1031/Activities'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 1932,
      "associatedContactIDs": [],
      "title": "Phone call",
      "activitySubType": {
        "id": -4,
        "title": "Phone Call"
      },

GET

Get Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/35/Activities/1001

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities/{ActivityID}"

This method fetches an Activity with the ID specified by ActivityID. The
Activity is for an Enquiry with the ID specified in EnquiryID. The ProjectID is
the ID of the Project the Contact, Enquiry and Activity is in.

Fetches a single Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/1031/Activities/1932'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 1932,
  "associatedContactIDs": [],
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

GET

Get Event Activity fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities/Fields

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities/Fields".

Where the EnquiryID is the ID of the Enquiry to select Activity Fields for. The
ProjectID is the ID of the Project the Contact, Enquiry and Activity is in.

Fetches the Fields which are available for this Project

If no query string parameters are specified in the URL then all Field types for
Building are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success - all fields

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/1031/Activities/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

POST

Add Event Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiry/{EnquiryID}/Activities".

Where the EnquiryID is the ID of the Enquiry the Activity is to be added to. The
ProjectID is the ID of the Project the Contact, Enquiry and Activity is in.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{    
    "associatedContactIDs": [
        3432,
        66
    ],
    "title": "Invitation Email sent by API",
    "activitySubType": {
        "id": -6,
        "title": "Email Invitation Sent"
    },
    "status": {



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/115/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1933,
  "associatedContactIDs": [],
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

PUT

Update Event Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Activities

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Enquiries/{EnquiryID}/Activities".

Where the EnquiryID is the ID of the Enquiry the Activity being updated belongs
to. The ProjectID is the ID of the Project the Contact, Enquiry and Activity is
in.

The ID property of the Activity in the Request body specifies the Activity to
update.

All properties of the Activity are overwritten with the supplied values. If no
values are supplied for a property, that property is set to null on the
Activity.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 1081,
    "associatedContactIDs": [
        3432,
        66
    ],
    "title": "Invitation Email sent by API",
    "activitySubType": {
        "id": -6,
        "title": "Email Invitation Sent"
    },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/115/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1933,
    "associatedContactIDs": [],
    "title": "Phone call",
    "activitySubType": {
        "id": -4,
        "title": "Phone Call"
    },
    "status": {

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
GET

Get Event


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/57

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Events/{EventID}/"

Where the ProjectID is the ID of the Project to select data for and the EventID
is the ID of the Event.

Fetches a single Event.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get Event

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/56'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 56,
  "title": "Introductory Meeting",
  "eventStartDate": "2019-02-25T10:00:00",
  "eventEndDate": "2019-02-25T12:00:00",
  "eventOverview": "",
  "allowRegistration": false,
  "isDisplayedOnWebsite": false,
  "eventCategory": {
    "id": 16,
    "title": "Meeting"

GET

Get Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Fields

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Events/Fields?"

Where the ProjectID is the ID of the Project to select data for.

Fetches the Fields which are available for this Event.

If no query string parameters are specified in the URL then all Field types for
Event are returned.

If you only require certain Field types then you can specify to only fetch those
fields by adding query string parameters with a key of "include" and a value of
the Field type. Multiple Field types can be specified by adding multiple query
string parameters

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
eventCategories

[Optional] The name of a Field type to return the Fields for

include
subProjects

[Optional] The name of a Field type to return the Fields for

include
eventStatuses

[Optional] The name of a Field type to return the Fields for



Get Fields - All Fields
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "eventCategories": [
    {
      "id": 4,
      "title": "Conference"
    },
    {
      "id": 17,
      "title": "Exhibition"
    },
    {

POST

Get all Events


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Search

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Events/Search?"

This method fetches a paged list of all Events in the Project specified by the
ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   100.
   

A request with no parameters will return the 1st page of results, with a maximum
of 100 records per page.

The pageCount property in the response body contains the number of available
pages.


SCHEMA

View More

Property DataType Required title String no dateFrom DateTime no dateTo DateTime
no isDisplayedOnWebsite True/False no
Please note that this field defaults to a value of 'True' eventCategories Array
of fields no eventSubProjects Array of fields no eventStatuses Array of fields
no eventThemes Array of fields no audienceCategories Array of fields no
audienceSubCategories Array of fields no areaCategories Array of fields no
areaSubCategories Array of fields no departmentCategories Array of fields no
departmentCategories Array of fields no interestCategories Array of fields no
interestSubCategories Array of fields no

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
PARAMS
pageIndex
0
pageSize
15
BODYraw

{
    "IsDisplayedOnWebsite":"true",
    "dateFrom":"2020-02-01T00:00:00",
    "dateTo":"2020-03-01T00:00:00"
}



Get all Events
Example Request
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Search' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "intro",
    "IsDisplayedOnWebsite":"false",
    "dateFrom":"2019-01-01T00:00:00",
    "dateTo":"2020-01-01T00:00:00",
    "eventCategories":[
    	{
    		"id":16
    	}

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 56,
      "title": "Introductory Meeting",
      "eventStartDate": "2019-02-25T10:00:00",
      "eventEndDate": "2019-02-25T12:00:00",
      "eventOverview": "",
      "allowRegistration": false,
      "isDisplayedOnWebsite": false,

GET

Get Attachments


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Attachments

URL in the format {RootUrl}/Projects/{ProjectID}/Events/{EventID}/Attachments.

This returns the ActivityID of all the specified Event's Activities which have
attachments, along with the Attachment IDs.

This is to allow you to determine which Activities have attachments, without
having to iterate over each individual Activity.

The data is returned in the format

Property DataType ActivityId Int AttachmentIds Array of Int

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Sucessful

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/35/Attachments'

Example Response
200 OK
Body
Header(5)
View More

[
  {
    "activityID": 1001,
    "attachmentIDs": [
      1267
    ]
  },
  {
    "activityID": 878,
    "attachmentIDs": [
      1080

GET

Get All Events for Project


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/?pageIndex=0&pageSize=15

The request URL is in the format "{RootURL}/Projects/{ProjectID}/Events"

This method fetches a paged list of all Events within the Project specified by
the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
15

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Example Request
Successful

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/?pageIndex=0&pageSize=15'

Example Response
200 OK
Body
Header(5)
View More

{
  "recordCount": 42,
  "pageCount": 3,
  "results": [
    {
      "id": 9,
      "title": "NECS Exhibition",
      "eventStartDate": "2019-09-09T09:00:00",
      "eventEndDate": "2019-09-09T17:00:00",
      "allowRegistration": false,
      "isDisplayedOnWebsite": false,

Distribution Lists


DESCRIPTION

A Distribution list is a group of either Contacts or Organisations, which are
grouped togeather for the purpose of communicating with that group. The most
common use for a distribution list is a list of Contacts to send an email
newsletter to.

DISTRIBUTION LIST TYPES

There are two types of Distribution List:

   
 * Contact
   
 * Organisation It is not possible to create a Distribution List that consists
   of both Contacts and Organisations.
   

DISTRIBUTION LIST FORMATS

Distribution lists can be created with four different formats, for different
communication methods:

   
 * Mailshots (Smartmailer/Mass emails)
     
   * This is for our Smartmailer product used for mass emails like newsletters.
     
   
 * Post
   
 * Telephone
   
 * SMS
   
 * Email (Plain Text)
     
   * This is intended for a smaller number of recipients than Mailshots, and
     where the recipient is specifically interested in the response as oppossed
     to a general communication like a newsletter. An example may be responding
     to a number of residents down a single road who have all submitted
     enquiries about the construction is taking place on that road.
     
   * Please note that whilst this is called Plain Text, it does actually send an
     HTML email but with greatly restricted formatting options compared to
     Mailshots.
     
   

CONTACT PERMISSIONS & SUBSCRIPTION PREFERENCES

Both Contacts and Organisations have contactPermitted and various
SubscriptionPreference properties. Whilst any Contact or Organisation can be
added to a Distribution List of the appropriate Distribution List Type you will
only be able to use the Distribution List to communicate with the Contact or
Organisation if they have the relevant data and Contact Permissions and
Subscription Preferences for the Distribution List Format.

In order for a Contact or Organisation to be valid on a Mailshot Distribution
List Format they would require:

   
 * A valid Email address
   
 * The Email Contact Permission
   
 * A mailshotSubscriptionPreference with a Status of Subscribed
   

In order for a Contact or Organisation to be valid on a Post Distribution List
Format they would require:

   
 * An Address
   
 * The Post Contact Permission
   
 * A postalSubscriptionPreference with a Status of Subscribed
   

In order for a Contact or Organisation to be valid on a Post Distribution List
Format they would require:

   
 * A valid Mobile number
   
 * The SMS Contact Permission
   
 * A smsSubscriptionPreference with a Status of Subscribed
   

In order for a Contact or Organisation to be valid on a SMS Distribution List
Format they would require:

   
 * A valid Mobile number
   
 * The SMS Contact Permission
   
 * A smsSubscriptionPreference with a Status of Subscribed
   

In order for a Contact or Organisation to be valid on a SMS Distribution List
Format they would require:

   
 * A valid Email address
   
 * The Email Contact Permission
   
 * They do not require a subscription Preference as Email (Plain Text) is not
   intended for mass communication where someone would subscribe/unsubscribe.
   

SCHEMA

Property DataType Required Restrictions id Integer no none name String Yes Max
length 256 characters Format Array of Field Yes None Type Field Yes None

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Contacts

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Add Contact to Distribution List


https://acme.tractivity.co.uk/API/V1/Projects/61/DistributionLists/Contacts

The URL is in the format
{RootURL}/Projects/{ProjectId}/DistributionLists/Contacts

This request adds a Contact to a Distribution List.

Property DataType Required distributionListId Int Yes contactId Int Yes

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
BODYraw

{
	"distributionListId":43,
	"ContactID":66
}



Example Request
Success

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/DistributionLists/Contacts' \
--data-raw '{
	"distributionListId":43,
	"ContactID":66
}'

Example Response
200 OK
Body
Header(6)

{
  "distributionListID": 43,
  "contactID": 66
}

GET

Get All Distribution Lists for Project


https://acme.tractivity.co.uk/API/V1/Projects/61/DistributionLists?pageIndex=0&pageSize=15

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/DistributionLists"

This method fetches a paged list of all Contacts within the Project specified by
the ProjectID.

There are two optional query string parameters:

   
 * pageIndex - The page of results to return. Starts at 0 which is also the
   default value.
   
 * pageSize - the maximum number of records to return per page. The default is
   15.
   

A request with no parameters will return the 1st page of results, with a maximum
of 15 records per page.

The pageCount property in the response body contains the number of available
pages.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
pageIndex
0

[Optional] defaults to 0 , which will return the 1st page of results

pageSize
15

[Optional] defaults to 15, which is the maximum number of records which can be
returned in one request



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/DistributionLists?pageIndex=0&pageSize=15'

Example Response
200 OK
Body
Header(8)
View More

{
  "recordCount": 16,
  "pageCount": 2,
  "results": [
    {
      "id": 80,
      "format": {
        "id": 6,
        "title": "Email (Plain-Text)"
      },
      "name": "Bucks stakeholders"

Attachments

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get Attachment


https://acme.tractivity.co.uk/API/V1/Projects/61/Attachments/1634?includeData=main

URL in the form {BaseUrl}/Projects/{ProjectID}/Attachments/{AttachmentID}

If you include the querystring parameter includeData=main then the file data as
bytes will be returned. If not then only the meta data is returned.

This request is rate limited to:

   
 * once per second
   
 * 30 times per minute
   

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
includeData
main

Optional - if this parameter is included then the fileAsByteArray property is
populated.



Successful with data
Example Request

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Attachments/1634?IncludeData=main'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 1634,
  "filename": "Example Document",
  "fileExtension": ".pdf",
  "originalFilename": "Example Document",
  "fileSize": "227Kb",
  "fileAsByteArray": "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cmlwdG9yIDYgMCBSL0ZpcnN0Q2hhciAzMi9MYXN0Q2hhciAxNjMvV2lkdGhzIDI3MyAwIFI+Pg0KZW5kb2JqDQo2IDAgb2JqDQo8PC9UeXBlL0ZvbnREZXNjcmlwdG9yL0ZvbnROYW1lL0FyaWFsLEJvbGQvRmxhZ3MgMzIvSXRhbGljQW5nbGUgMC9Bc2NlbnQgOTA1L0Rlc2NlbnQgLTIxMC9DYXBIZWlnaHQgNzI4L0F2Z1dpZHRoIDQ3OS9NYXhXaWR0aCAyNjI4L0ZvbnRXZWlnaHQgNzAwL1hIZWlnaHQgMjUwL0xlYWRpbmcgMzMvU3RlbVYgNDcvRm9udEJCb3hbIC02MjggLTIxMCAyMDAwIDcyOF0gPj4NCmVuZG9iag0KNyAwIG9iag0KPDwvVHlwZS9Gb250L1N1YnR5cGUvVHJ1ZVR5cGUvTmFtZS9GMi9CYXNlRm9udC9BcmlhbC9FbmNvZGluZy9XaW5BbnNpRW5jb2RpbmcvRm9udERlc2NyaXB0b3IgOCAwIFIvRmlyc3RDaGFyIDMyL0xhc3RDaGFyIDE2My9XaWR0aHMgMjc3IDAgUj4+DQplbmRvYmoNCjggMCBvYmoNCjw8L1R5cGUvRm9udERlc2NyaXB0b3IvRm9udE5hbWUvQXJpYWwvRmxhZ3MgMzIvSXRhbGljQW5nbGUgMC9Bc2NlbnQgOTA1L0Rlc2NlbnQgLTIxMC9DYXBIZWlnaHQgNzI4L0F2Z1dpZHRoIDQ0MS9NYXhXaWR0aCAyNjY1L0ZvbnRXZWlnaHQgNDAwL1hIZWlnaHQgMjUwL0xlYWRpbmcgMzMvU3RlbVYgNDQvRm9udEJCb3hbIC02NjUgLTIxMCAyMDAwIDcyOF0gPj4NCmVuZG9iag0KOSAwIG9iag0KPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTAvQmFzZUZvbnQvQXJpYWwvRW5jb2RpbmcvSWRlbnRpdHktSC9EZXNjZW5kYW50Rm9udHMgMTAgMCBSL1RvVW5pY29kZSAyNzQgMCBSPj4NCmVuZG9iag0KMTAgMCBvYmoNClsgMTEgMCBSXSANCmVuZG9iag0KMTEgMCBvYmoNCjw8L0Jhc2VGb250L0FyaWFsL1N1YnR5cGUvQ0lERm9udFR5cGUyL1R5cGUvRm9udC9DSURUb0dJRE1hcC9JZGVudGl0eS9EVyAxMDAwL0NJRFN5c3RlbUluZm8gMTIgMCBSL0ZvbnREZXNjcmlwdG9yIDEzIDAgUi9XIDI3NiAwIFI+Pg0KZW5kb2JqDQoxMiAwIG9iag0KPDwvT3JkZXJpbmcoSWRlbnRpdHkpIC9SZWdpc3RyeShBZG9iZSkgL1N1cHBsZW1lbnQgMD4+DQplbmRvYmoNCjEzIDAgb2JqDQo8PC9UeXBlL0ZvbnREZXNjcmlwdG9yL0ZvbnROYW1lL0FyaWFsL0ZsYWdzIDMyL0l0YWxpY0FuZ2xlIDAvQXNjZW50IDkwNS9EZXNjZW50IC0yMTAvQ2FwSGVpZ2h0IDcyOC9BdmdXaWR0aCA0NDEvTWF4V2lkdGggMjY2NS9Gb250V2VpZ2h0IDQwMC9YSGVpZ2h0IDI1MC9MZWFkaW5nIDMzL1N0ZW1WIDQ0L0ZvbnRCQm94WyAtNjY1IC0yMTAgMjAwMCA3MjhdIC9Gb250RmlsZTIgMjc1IDAgUj4+DQplbmRvYmoNCjE0IDAgb2JqDQo8PC9UeXBlL1hPYmplY3QvU3VidHlwZS9JbWFnZS9XaWR0aCA4ODUvSGVpZ2h0IDIwMS9Db2xvclNwYWNlL0RldmljZVJHQi9CaXRzUGVyQ29tcG9uZW50IDgvSW50ZXJwb2xhdGUgZmFsc2UvRmlsdGVyL0ZsYXRlRGVjb2RlL0xlbmd0aCAyNzk0OD4+DQpzdHJlYW0NCnic7H0JdBTV1u5aksR/eK5//eutd9/zQhPCGAJJOgmBREWmQEBmENB7FRHC4BVl/gljuIDgRQkXRAyTKJMgIl4vXEAyhwSQOQkzCkJkCAlD5qS7U+9Une6T01Xd1TV2ZdgfexXVlao6Q51z6qu999mHYQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD0RW1trdFZAAAAAAAA0FAhTiTIX4FvAAAAAAAAAACkwyN7xCdodRqgvgEeGQAAAAAAAA0hwgmlsA7eOfRPb5IWIEgqARUIAAAAAABAc7hjhlJ0kiIk0zswsWgOokJM3bp1

GET

Get All Projects


https://acme.tractivity.co.uk/API/V1/Projects

The request URL is in the format "{RootURL}/Projects".

This will return all Projects which you have authorisation to see.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get All Projects - Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

GET

Get Me


https://acme.tractivity.co.uk/API/V1/Me

The request URL is in the format "{RootURL}/Projects".

This will return all Projects which you have authorisation to see.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get Me - Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

Examples


DESCRIPTION

This section contains examples of how to interact with the Tractivity API to
fulfil specific use-cases. These examples guide you through the logical steps,
that is what requests needs to be made, in what order and why.
For detailed information about how each request works, please see the API
Structure section.


GLOSSARY

The following terms will be used repeatedly throughout the Examples section

View More

Term Meaning Client The Client refers to the organisation who have purchased the
Tractivity system and have comissioned the work you are doing. In addition to
setting the requirements of the work it may be possible that only the Client has
access to the System Administrator functions of Tractivity. Stakeholder
Tractivity is a Stakeholder management system. Contacts and Organisations are
both types of Stakeholders. For example if you are using the Tractivity API to
present a publicly accessible HTML Form, the members of the public submitting
the form will be Stakeholders. Tractivity System Administrator The Tractivity
System Administrator's have the ability to Add, Edit and Remove API Credentials,
most Field options and Tractivity Users. The Tractivity System Administrator's
will be amongst the Client's staff, unless you have been given such access in
the Tractivity System.


STATIC DATA

Several the examples in this section use or return Static Data, this is data
this will not change unless the Client deliberately changes it from within
Tractivity as System Administrators. As the Client can change the data It is
recommended that this Static data is stored in configuration such that it can be
changed without needing to recompile your application. Please note that as Stage
and Live Tractivity maintain separate databases that there may be a disparity
between the Static Data returned from the Stage and Live versions of the API.

For example, if the Client needs to add a Field option to Contact Stakeholder
Category they will need to do this twice - once for the Stage and once for the
Live system. The ID for the field may be different on the Stage Tractivity than
it is on the Live Tractivity. When preparing to put your application into
production, first check the values of any Static data on the Live Tractivity.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Contact newsletter signup


DESCRIPTION

This example show you how to use the Tractivity API to sign an individual up to
receiving marketing communications. The logical steps involved are:

    
 1. Determining what data is needed before hand.
    
 2. Fetching the Fields to populate the UI displayed to the end-user.
    
 3. Check to see if the Stakeholder already exists as a Contact within
    Tractivity.
    
 4. If a Contact already exists, update it.
    
 5. If no appropriate Contact exists in Tractivity, create a Contact.
    
 6. [Optional] Create an Activity to alert the Client that the Contact has
    signed-up.
    

N.B Subsequent to creating this example we have added a method Organisation,
Contact & Address which can be used to perform steps 3,4 & 5 in one request at
the expense of flexibility when determinine what constitutes a duplicate and how
to update them. Please read Organisation, Contact & Address for more
information.

DETERMINING WHAT DATA IS NEEDED BEFORE HAND.

This step will largely involve coordinating with the Client who is requesting
this feature. From them you will need to know:

   
 * What Project does the Client want to allow sign-ups for?
   
 * What Teams should have access to the submitted data?
   
 * What properties on a Contact need to match the submitted data in order to
   consider that Contact to already exist within Tractivity. (The default is
   firstName, lastName & email).
   
 * Does the Client want an Activity to be created when a Stakeholder signs up?
   
 * If an Activity is to be created, what should the Activity Title be?
   
 * If an Activity is to be created, is this simply for audit purposes, or should
   the Activity also act to alert the Client to take action?
   
 * If an Activity is to be created, and it is to alert the Client, which
   Tractivity Teams should be alerted?
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Authenticate using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

Back to Contact newsletter signup.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Example Request
Get Token using Client Credentials

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

GET

Get All Projects - static data


https://acme.tractivity.co.uk/API/V1/Projects

Returns all Projects for the Tractivity System.

In this example you will use the ProjectID of 61 as you have already confirmed
with the Tractivity Users that they only wish to use the "South Yorkshire Wind
Turbines" Project.

This value will not change unless the Client deliberately changes it. Therefore
this value could be stored in a configuration file, rather than being fetched
each time the form loads

For more details of this request see Get All Projects.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

GET

Get Contact Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=subscriptionMethods&include=contactPermissions&include=subscriptionStatuses

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

In this request we have used the optional include querystring parameters to
return only the fields we want.

SUBSCRIPTION METHOD

The Subscription Method is used by the Client to determine how a Stakeholder
recorded their marketing preference. This may be useful to the Client in the
event of a GDPR audit.

It may be that the Client will create a Subscription Method specifically for
your form.

In this example the Client has chosen the Subscription Method of "Website" (ID
2).

SUBSCRIPTION STATUSES

The Subscription Status Field values do not change. If a Stakeholder signs-up to
the newsletter their MailshotNewsletterSubscriptionPreference Status will be set
to "Subscribed" (id 2).

CONTACT PERMISSIONS

In Tractivity the Contact Permission restricts in what ways the Tractivity
system can be used to interact with a Stakeholder.

This is distinct from the Subscription Preference in that Subscription
Preferences specifically refer to Marketing & Mass communications, whereas
Contact Permissions also include how a Stakeholder can be contacted in
one-to-one communications.

For example a Contact which has a Mailshot Subscription Preferences of
Unsubscribed, and a Contact Permission of Email cannot be sent a Newsletter, but
could be sent an email in response to an Enquiry the Stakeholder has sent to the
Client.

In this example where a Stakeholder signing up for a newsletter the Contact will
need to have a Contact Permited of "email" (id -1)

For more details of this request see Get Contact Fields.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
subscriptionMethods
include
contactPermissions
include
subscriptionStatuses


Example Request
Get static Fields

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=subscriptionMethods&include=contactPermissions&include=subscriptionStatuses'

Example Response
200 OK
Body
Header(3)
View More

{
  "titles": [],
  "suffixes": [],
  "contactPermissions": [
    {
      "id": -1,
      "title": "Email"
    },
    {
      "id": -2,
      "title": "Post"

GET

Get Contact Activity Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams

This request is only required if the Client wants a Contact Activity to be
created.

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

The Field values fetched are Teams, Activity Status and Activity Sub Type.

OWNER TEAMS

Owner Teams in Tractivity donate which Client users are able to edit data within
Tractivity. The Client is able to create and remove Owner Teams, so if they
specify an Owner Team to be used, they must be aware that removing that Team
would cause problems for this form.

In this example the Client has chosen to use a single Owner Team of "South
Yorkshire Wind Farm" (ID 2121). The Client has also determined that the entire
"South Yorkshire Wind Farm" team will be alerted when a Stakeholder signs up.

It is possible for multiple Owner Teams to be used, and it is possible for the
Client to create additional Owner Teams that they may wish to use.

ACTIVITY STATUS

The Activity Status determines whether or not the Activity requires the Client
to perform an action.
An Activity Status of "Pending" denotes an Activity which requires the Client to
take action.
A "Pending" Activity will be displayed on the Allocated To Team's home page in
Tractivity.
An Activity Status of "Completed" denotes an Activity for which action has
already been taken.
As the Client in this example wants to be alerted to take action use "Pending"
(1).

ACTIVITY SUB TYPE

The Activity Sub Type is used to specify what action the Activity is
recording/prompting. It may be that the Client will create an Activity Sub Type
specifically for your form.
In this example use "Follow-Up" 1028.

For more details of this request see Get Contact Activity Fields.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activitySubTypes
include
activityStatuses
include
Teams


Example Request
Get Contact Activity Fields - static data

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams'

GET

Get Contact Fields - fetch each time


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=titles

This request is used to fetch options to display to the Stakeholder when the
form is rendered.

In this case the only Field we shall be displaying is the Titles Field. In order
to reduce the time taken for the request, we have added the query string
parameter "include=titles" so that only the Titles field is fetched.

The available field values can be altered by the Client, so it is not possible
to permanently store the options, and the Fields will need to be fetched from
the Tractivity API.

However these Fields are not often changed and it is likely that the result can
be cached to increase performance. A suggested cache lifetime is 1 hour, it
would be best to discuss any cache lifetime with the Client.

For more details of this request see Get Contact Fields.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
titles


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=titles'

Example Response
200 OK
Body
Header(6)
View More

{
  "titles": [
    {
      "id": 85,
      "title": "Ch.Supt."
    },
    {
      "id": 76,
      "title": "Cllr"
    },
    {

POST

Find Contact duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates

You will need to discuss with the Client how to match submitted data with
existing data within Tractivity.

By default in Tractivity the match for a Contact checks on the Contact
firstName, lastName and email. If the Client wishes for more detailed checks
then you will need to check against the data returned in the body of the
response to this request.

In this example when the Stakeholder has submitted the form this request checks
to see if any Contacts already exist within the "South Yorkshire Wind Farm"
project with the same firstName, lastName and email address. Here duplicates
have been found, select the first Contact returned as the matching Contact.
Update the Contact with the submitted information.

For more details of this request see Find Contact duplicates.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"firstName":"Reg",
	"lastName":"Mint",
	"email":"Reg.Mint@anemaildomain.com"
}



Duplicate found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"firstName":"Joseph",
	"lastName":"Northern",
	"email":"j.northern@sheffieldwindturbines.com"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 114,
    "title": {
      "id": 5,
      "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],
    "email": "j.northern@sheffieldwindturbines.com",

PUT

Update Contact (if duplicate found match)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

If an existing contact was found in Find Contact duplicates, update that contact
with the new submitted information.

Ensure that there is a Contact Permission of -1,

Update the mailshotSubscriptionPreference. In order to update the preference
submit the preference without an id. Set the Status, Method, and populated the
CreatedBy information.

As no other Subscription Preferences are being updated leave their IDs in the
request.

For more details of this request see Contacts and Update Contacts.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "suffixes": [],
        "email": "j.northern@sheffieldwindturbines.com",
        "telephone": "0114 565879",



Example Request
Successful update
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 114,
    "title": {
        "id": 5,
        "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

If no duplicate was found then Create a new contact with the submitted
information.

For more details of this request see Contacts and Add Contacts.

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "title": {
            "id": 5
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "email": "j.northern@sheffieldwindturbines.com",
        "contactPermitted": [
            {
                "id": -1
            }



Example Request
Create Contact
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "title": {
            "id": 5
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "email": "j.northern@sheffieldwindturbines.com",
        "contactPermitted": [
            {

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 118,
  "title": {
    "id": 5
  },
  "firstName": "Joseph",
  "lastName": "Northern",
  "suffixes": [],
  "email": "j.northern@sheffieldwindturbines.com",
  "contactPermitted": [
    {

POST

Add Contact Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/36/Activities

In this optional request you create a Contact Activity which will alert the
Client to take further action.

The Activity is associated to the Contact we created/updated through the use of
the Contact's ID in the request URL.

In order to ensure that the Client's chosen Team is alerted, set the Actvity
properties "allocatedToTeams" and "ownerTeams" to contain the Client's chosen
Team.

Set the Start Date and End Date to the date on which the Stakeholder submitted
the data.

For more details of this request see Contact Activity and Add Contact Activity

Back to Contact newsletter signup.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Contact Newsletter Sign-up",
    "activitySubType": {
            "id": 1028
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has signed-up for a newsletter",
    "ownerTeams": [
        {



Example Request
Create Activity
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Contact Newsletter Sign-up",
    "activitySubType": {
            "id": 1028
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has signed-up for a newsletter",

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1934,
  "title": "Contact Newsletter Sign-up",
  "activitySubType": {
    "id": 1028
  },
  "activitySubProject": {
    "id": 2
  },
  "status": {
    "id": 1

Contact registration


DESCRIPTION

This example shows you how to use the Tractivity API to add a Contact to a
Project in Tractivity. This could be used in the situation where the Client has
tasked you with creating a UI for use by the Client's own staff who will be
talking to Stakeholders and adding them as Contacts to Tractivity.

The logical steps involved are:

     
 1.  Determining what data is needed before hand.
     
 2.  Fetching the Fields to populate the UI displayed to the end-user.
     
 3.  Check to see if the Stakeholder already exists as a Contact within
     Tractivity.
     
 4.  If a Contact already exists, update it.
     
 5.  If no appropriate Contact exists in Tractivity, create a Contact.
     
 6.  If address details have been supplied, check to see if the Building already
     exists.
     
 7.  If the Building exists, update it.
     
 8.  If no matching Building exists, create it.
     
 9.  Check to see if the Building has already been added to the Contact as an
     Address.
     
 10. If the Address exists, update it.
     
 11. If no matching Address exists, create it.
     
 12. [Optional] Create an Activity to alert the Client that the Contact has
     registered.
     

N.B Subsequent to creating this example we have added a method Organisation,
Contact & Address which can be used to perform steps 4-11 in one request at the
expense of flexibility when determinine what constitutes a duplicate and how to
update them. Please read Organisation, Contact & Address for more information.

DETERMINING WHAT DATA IS NEEDED BEFORE HAND.

This step will largely involve coordinating with the Client who is requesting
this feature. From them you will need to know:

   
 * What Project does the Client want to allow registration for?
   
 * What Contact properties will be available, therefore which Contact Fields
   need to be fetched?
   
 * What Teams should have access to the submitted data?
   
 * What properties on a Contact are used to determine whether or not the Contact
   already exists in Tractivity. (The default is firstName, lastName & email).
   
 * Does the Client want an Activity to be created when a Stakeholder signs up?
   
 * If an Activity is to be created, what should the Activity Title be?
   
 * If an Activity is to be created, is this simply for audit purposes, or should
   the Activity also act to alert the Client to take action?
   
 * If an Activity is to be created, and it is to alert the Client, which
   Tractivity Teams should be alerted?
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Authenticate using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

Back to Contact Registration.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Example Request
Get Token using Client Credentials

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

GET

Get All Projects - static data


https://acme.tractivity.co.uk/API/V1/Projects

Returns all Projects for the Tractivity System, which can be accessed with your
provided API Credentials.

In this example you will use the ProjectID of 61 as you have already confirmed
with the Tractivity Users that they only wish to use the "South Yorkshire Wind
Turbines" Project.

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

If however you decided to present the end-user with a choice of Project, this
response could be cached as it changes infrequently. The cache duration would
depend on how frequently the Client adds Projects. A suggested duration would be
one hour.

For more details of this request see Get All Projects.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

GET

Get Contact Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=subscriptionMethods&include=subscriptionStatuses&include=contactPermissions

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

In this request use the optional include querystring parameters to return only
the fields we want.

SUBSCRIPTION STATUSES

The Subscription Status Field values do not change, and therefore can be stored
in a configuration value to reduce the size of requests to the API and improve
performance of the UI.

SUBSCRIPTION METHOD

The Subscription Method is used by the Client to determine how a Stakeholder
recorded their marketing preference. This may be useful to the Client in the
event of a GDPR audit.

In this example the Client has created the Subscription Method of "Registration
Form" (ID 9).

CONTACT PERMISSIONS

In Tractivity the Contact Permission restricts in what ways the Tractivity
system can be used to interact with a Stakeholder.

This is distinct from the Subscription Preference in that Subscription
Preferences specifically refer to Marketing & Mass communications, wheras
Contact Permissions also include how a Stakeholder can be contacted in
one-to-one communications.

For example a Contact which has a Mailshot Subscription Preferences of
Unsubscribed, and a Contact Permission of Email cannot be sent a Newsletter, but
could be sent an email in response to an Enquiry the Stakeholder has sent to the
Client.

The Contact Permission Fields do not change and so can be stored in a
configuration file to improve the performance of the UI.

For more details of this request see Get Contact Fields.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
subscriptionMethods
include
subscriptionStatuses
include
contactPermissions


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Fields?include=ownerTeams&include=subscriptionMethods&include=subscriptionStatuses&include=contactPermissions'

Example Response
200 OK
Body
Header(6)
View More

{
  "titles": [],
  "suffixes": [],
  "contactPermissions": [
    {
      "id": -1,
      "title": "Email"
    },
    {
      "id": -2,
      "title": "Post"

GET

Get Contact Activity Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams&include=accountGroups

This request is only required if the Client wants a Contact Activity to be
created.

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

The Field values fetched are Teams, Activity Status and Activity Sub Type.

OWNER TEAMS

Owner Teams in Tractivity donate which Client users are able to edit data within
Tractivity. The Client are able to create and remove Owner Teams, so if they
specify an Owner Team to be used, they must be aware that removing that Team
would cause problems for this form.

In this example the Client has chosen to use a single Owner Team of "South
Yorkshire Wind Farm" (ID 2121). The Client has also determined that the entire
"South Yorkshire Wind Farm" team will be alerted when a Stakeholder is
registered.

It is possible for multiple Owner Teams to be used, and it is possible for the
Client to create additional Owner Teams that they may wish to use.

ACTIVITY STATUS

The Activity Status determines whether or not the Activity requires the Client
to perform an action.
An Activity Status of "Pending" denotes an Activity which requires the Client to
take action.
A "Pending" Activity will be displayed on the Allocated To Team's home page in
Tractivity.
An Activity Status of "Completed" denotes an Activity for which action has
already been taken.
As the Client in this example wants to be alerted to take action use "Pending"
(1).

ACTIVITY SUB TYPE

The Activity Sub Type is used to specify what action the Activity is
recording/prompting. It may be that the Client will create an Activity Sub Type
specifically for your form.
In this example use "Contact Registered" 1039.

For more details of this request see Get Contact Activity Fields.

Back to Contact registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activitySubTypes
include
activityStatuses
include
Teams
include
accountGroups


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams&include=accountGroups'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

POST

Batch get Fields - fetch each time.


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

This request is used to fetch Fields to display to the Stakeholder when the form
is rendered.

This example requires you to create or update Contacts, Buildings and Contact
Addresses.

As you are selecting fields for multiple Entities use the Batch Fields to select
the Fields for multiple Entities at once.
This will increase performance compared to a request per Entity type.

However these Fields are not often changed and it is likely that the result can
be cached to increase performance. A suggested cache lifetime is 1 hour, it
would be best to discuss any cache lifetime with the Client.

For more details of this request see Batch Get Fields.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [
        "counties",
        "buildingTypes"



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [

Example Response
200 OK
Body
Header(6)
View More

{
  "addressFields": {
    "relationships": [
      {
        "id": 3,
        "title": "Building Manager"
      },
      {
        "id": 1,
        "title": "Building Owner"
      },

POST

Find Contact duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates

You will need to discuss with the Client how to match submitted data with
existing data within Tractivity.

Whenever any automatic matching of partial data takes place in any system there
is always some possibility of an incorrect match which will result in
overwriting good data. There is also always some possibility that there will not
be a match and duplicate entries are created.

By default in Tractivity the match for a Contact checks on the Contact
firstName, lastName and email. If the Client wishes for more detailed checks
then you will need to check against the data returned in the body of the
response to this request.

In this example when the Stakeholder has submitted the form this request checks
to see if any Contacts already exist within the "South Yorkshire Wind Farm"
project with the same firstName, lastName and email address. Here duplicates
have been found, select the first Contact returned as the matching Contact and
proceed to update the Contact with the new information.

For more details of this request see Find Contact duplicates.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"firstName":"Reg",
	"lastName":"Mint",
	"email":"Reg.Mint@anemaildomain.com"
}



Duplicate found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"firstName":"Joseph",
	"lastName":"Northern",
	"email":"j.northern@sheffieldwindturbines.com"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 114,
    "title": {
      "id": 5,
      "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],
    "email": "j.northern@sheffieldwindturbines.com",

POST

Find Contact with Email and Portal Password


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates

You will need to discuss with the Client how to match submitted data with
existing data within Tractivity.

Whenever any automatic matching of partial data takes place in any system there
is always some possibility of an incorrect match which will result in
overwriting good data. There is also always some possibility that there will not
be a match and duplicate entries are created.

By default in Tractivity the match for a Contact checks on the Contact
firstName, lastName and email. If the Client wishes for more detailed checks
then you will need to check against the data returned in the body of the
response to this request.

In this example when the Stakeholder has submitted the form this request checks
to see if any Contacts already exist within the "South Yorkshire Wind Farm"
project with the same firstName, lastName and email address. Here duplicates
have been found, select the first Contact returned as the matching Contact and
proceed to update the Contact with the new information.

For more details of this request see Find Contact duplicates.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"email":"Reg.Mint@anemaildomain.com",
	"portalPassword":"k43B2+3BjDm=h7v3"
}



Duplicate found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"firstName":"Joseph",
	"lastName":"Northern",
	"email":"j.northern@sheffieldwindturbines.com"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 114,
    "title": {
      "id": 5,
      "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],
    "email": "j.northern@sheffieldwindturbines.com",

PUT

Update Contact (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

If an existing Contact which matches the Stakeholder was found in the previous
request, the Update the Contact with the submitted information.

In this example the Stakeholder has updated all their Subscription Preferences.
Even if the status has not changed the Client needs you to record that the
Stakeholder confirmed their their subscription preference at that time.
As such all Subscription Preferences are submitted without id properties so that
new Subscription Preference records are created. As the Client's staff are using
the form the Created By information used is that of the staff member.

For more details of this request see Contacts and Update Contacts.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,
            "name": "Tower, Steven"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

If no duplicate was found then add a new Contact for that Stakeholder.

For more details of this request see Contacts and Add Contacts.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,
            "name": "Tower, Steven"
        },



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 119,
  "title": {
    "id": 5,
    "title": "Mr"
  },
  "firstName": "Joseph",
  "lastName": "Northern",
  "suffixes": [],
  "email": "j.northern@sheffieldwindturbines.com",
  "telephone": "0114 565879",

POST

Find Building duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates

In this example the Stakeholder has submitted their Address.

This request checks to see if the Building already exists within Tractivity.

By default this check is performed by finding any Buildings with the same
postcode that contain the same Building Name or Number and Road.

For a more detailed check, you will need to the match against the data returned
in the body of the response to this request.

For more details of this request see Find Building Duplicates.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"postcode":"DE451GT",
	"buildingNameNumberRoad":"Systems House"
}



Success - no duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"postcode":"S101hQ",
	"buildingNameNumberRoad":"14"
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Building (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If the Building already exists in Tractivity, update it.

For more details of this request see Buildings and Update Building.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

[
    {
        "id": 2080,
        "postcode": "DE451GT",
        "buildingNameNumberRoad": "SYstems House",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 1,
            "title": "Office"
        },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '
    {
        "id": 2080,
        "postcode": "DE451GT",
        "buildingNameNumberRoad": "SYstems House",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 1,

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Building (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If no existing Building was found then create a new Building.

For more details of this request see Buildings and Add Building.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More


    {
        "postcode": "S101HT",
        "buildingNameNumberRoad": "14",
        "locality": "",
        "town": {
            "id": 2
        },
        "buildingType": {
            "id": 6
        }



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '
    {
        "postcode": "S101HT",
        "buildingNameNumberRoad": "14",
        "locality": "",
        "town": {
            "id": 2
        },
        "buildingType": {

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2081,
  "postcode": "S101HT",
  "buildingNameNumberRoad": "14",
  "locality": "",
  "town": "Bakewell",
  "buildingType": {
    "id": 6
  },
  "longitude": -1.5059,
  "latitude": 53.3871

POST

Find Contact Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Duplicates

Now that you have the Contact and Building ids you can create a Contact Address.

This request checks to see if a matching Contact Address already exists.

For more details of this request see Find Contact Address duplicates.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}



No existing address found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Contact Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses

If an existing Contact Address has been found which matched the submitted
information update it.

As this has been submitted as the Contact's current address, we ensure that the
Detached property is set to false. This indicates that the Address is current.

The Contact against which the Address is created is specified by using the
Contact id in the URL.

For more information on this request see Contact Address and Update Contact
Address.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 2074,
    "unitNumber": "Systems House",
    "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": {
            "id": 2,
            "title": "Sheffield"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 2074,
    "unitNumber": "Systems House",
    "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": {

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Create new Contact Address (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses

If no matching address was found create a new Contact Address.
The Contact against which the Address is created is specified by using the
Contact id in the URL.


For more information on this request see Contact Address and Add Contact
Address.

Back to Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    },
    "relationship":{
    	"id":2
    },
    "DefaultAddress":true,
    "Detached":false
}



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    },
    "relationship":{
    	"id":2
    },
    "DefaultAddress":true,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2073,
  "unitNumber": "Systems House",
  "building": {
    "id": 2074,
    "postcode": "S9 1TL",
    "buildingNameNumberRoad": "Foundary Road",
    "locality": "The Mills",
    "town": {
      "id": 2,
      "title": "Sheffield"

POST

Add Contact Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Activities

In this optional request you create a Contact Activity which will alert the
Client to take further action.

The Activity is associated to the Contact we created/updated through the use of
the Contact's ID in the request URL.

In order to ensure that the Client's chosen Team is alerted, set the Actvity
properties "allocatedToTeams" and "ownerTeams" to contain the Client's chosen
Team.

Set the Start Date and End Date to the date on which the Stakeholder submitted
the data.

For more details of this request see Contact Activity and Update Contact
Activity

Back to Contact registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Contact Registration",
    "activitySubType": {
            "id": 1039
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has registered",
    "ownerTeams": [
        {



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Contact Registration",
    "activitySubType": {
            "id": 1039
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has registered",

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1938,
  "title": "Contact Registration",
  "activitySubType": {
    "id": 1039
  },
  "status": {
    "id": 1
  },
  "notes": "A Contact has registered",
  "ownerTeams": [

Organisation registration


DESCRIPTION

This example show you how to use the Tractivity API to add an Organisation to a
Project in Tractivity. This could be used in the situation where the Client has
tasked you with creating a UI for use by the Client's own staff who will be
talking to Stakeholders and adding them as Contacts to Tractivity.

The logical steps involved are:

     
 1.  Determining what data is needed before hand.
     
 2.  Fetching the Fields to populate the UI displayed to the end-user.
     
 3.  Check to see if the Stakeholder already exists as an Organisation within
     Tractivity.
     
 4.  If a Organisation already exists, update it.
     
 5.  If no appropriate Organisation exists in Tractivity, create an
     Organisation.
     
 6.  If address details have been supplied, check to see if the Building already
     exists.
     
 7.  If the Building exists, update it.
     
 8.  If no matching Building exists, create it.
     
 9.  Check to see if the Building has already been added to the Organisation as
     an Address.
     
 10. If the Address exists, update it.
     
 11. If the no matching Address exists, create it.
     
 12. [Optional] Create an Activity to alert the Client that the Organisation has
     registered.
     

N.B Subsequent to creating this example we have added a method Organisation,
Contact & Address which can be used to perform steps 4-11 in one request at the
expense of flexibility when determinine what constitutes a duplicate and how to
update them. Please read Organisation, Contact & Address for more information.

DETERMINING WHAT DATA IS NEEDED BEFORE HAND.

This step will largely involve coordinating with the Client who is requesting
this feature. From them you will need to know:

   
 * What Project does the Client want to allow registration for?
   
 * What Organisation and Building Fields should be available?
   
 * What Teams should have access to the submitted data?
   
 * What properties on an Organisation need to match the submitted data in order
   to consider that Organisation to already exist within Tractivity.
   
 *   
   * Does the Client want an Activity to be created when a Stakeholder signs up?
     
   
 * If an Activity is to be created, what should the Activity Title be?
   
 * If an Activity is to be created, is this simply for audit purposes, or should
   the Activity also act to alert the Client to take action?
   
 * If an Activity is to be created, and it is to alert the Client, which
   Tractivity Teams should be alerted?
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Authenticate using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

Back to Organisation Registration.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Example Request
Get Token using Client Credentials

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

GET

Get All Projects


https://acme.tractivity.co.uk/API/V1/Projects

Returns all Projects for the Tractivity System, which can be accessed with your
provided API Credentials.

In this example you will use the ProjectID of 61 as you have already confirmed
with the Tractivity Users that they only wish to use the "South Yorkshire Wind
Turbines" Project.

The Client have confirmed that this will not change so we can store this value
in a configuration file, rather than fetching the data each time the form loads.

If however you decided to present the end-user with a choice of Project, this
response could be cached as it changes infrequently. The cache duration would
depend on how frequently the Client adds Projects. A suggested duration would be
one hour.

For more details of this request see Get All Projects.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

GET

Get Organisation Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Fields?include=subscriptionStatuses&include=subscriptionMethods&include=contactPermissions

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

SUBSCRIPTION STATUSES

The Subscription Status Field values do not change, and therefore can be stored
in a configuration value to reduce the size of requests to the API and improve
performance of the UI.

SUBSCRIPTION METHOD

The Subscription Method is used by the Client to determine how a Stakeholder
recorded their marketing preference. This may be useful to the Client in the
event of a GDPR audit.

In this example the Client has created the Subscription Method of "Registration
Form" (ID 9).

CONTACT PERMISSIONS

In Tractivity the Contact Permission restricts in what ways the Tractivity
system can be used to interact with a Stakeholder.

This is distinct from the Subscription Preference in that Subscription
Preferences specifically refer to Marketing & Mass communications, wheras
Contact Permissions also include how a Stakeholder can be contacted in
one-to-one communications.

For example an Organisation which has a Mailshot Subscription Preferences of
Unsubscribed, and a Contact Permission of Email cannot be sent a Newsletter, but
could be sent an email in response to an Enquiry the Stakeholder has sent to the
Client.

The Contact Permission Fields do not change and so can be stored in a
configuration file to improve the performance of the UI.

For more details of this request see Get All Organisation Fields.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
PARAMS
include
subscriptionStatuses
include
subscriptionMethods
include
contactPermissions


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Fields?include=subscriptionStatuses&include=subscriptionMethods&include=contactPermissions' \
--header 'Content-Type: application/json' \
--data-raw ''

Example Response
200 OK
Body
Header(6)
View More

{
  "accountHandlers": [],
  "contactPermissions": [
    {
      "id": -1,
      "title": "Email"
    },
    {
      "id": -2,
      "title": "Post"
    },

GET

Get Organisation Activity Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams

This request is only required if the Client wants an Organisation Activity to be
created.

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

The Field values fetched are Teams, Activity Status and Activity Sub Type.

OWNER TEAMS

Owner Teams in Tractivity donate which Client users are able to edit data within
Tractivity. The Client are able to create and remove Owner Teams, so if they
specify an Owner Team to be used, they must be aware that removing that Team
would cause problems for this form.

In this example the Client has chosen to use a single Owner Team of "South
Yorkshire Wind Farm" (ID 2121). The Client has also determined that the entire
"South Yorkshire Wind Farm" team will be alerted when a Stakeholder is
registered.

It is possible for multiple Owner Teams to be used, and it is possible for the
Client to create additional Owner Teams that they may wish to use.

ACTIVITY STATUS

The Activity Status determines whether or not the Activity requires the Client
to perform an action.
An Activity Status of "Pending" denotes an Activity which requires the Client to
take action.
A "Pending" Activity will be displayed on the Allocated To Team's home page in
Tractivity.
An Activity Status of "Completed" denotes an Activity for which action has
already been taken.
As the Client in this example wants to be alerted to take action use "Pending"
(1).

ACTIVITY SUB TYPE

The Activity Sub Type is used to specify what action the Activity is
recording/prompting. It may be that the Client will create an Activity Sub Type
specifically for your form.
In this example use "Organisation Registration" 1144.

For more details of this request see Get Organisation Activity Fields.

Back to Organisation registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activitySubTypes
include
activityStatuses
include
Teams


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

POST

Batch get Fields - fetch each time


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

This request is used to fetch Fields to display to the Stakeholder when the form
is rendered.

This example requires you to create or update Organisations, Buildings and
Organisation Addresses.

As you are selecting fields for multiple Entities use the Batch Fields to select
the Fields for multiple Entities at once.
This will increase performance compared to a request per Entity type.

However these Fields are not often changed and it is likely that the result can
be cached to increase performance. A suggested cache lifetime is 1 hour, it
would be best to discuss any cache lifetime with the Client.

For more details of this request see Batch Get Fields.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [
        "counties",
        "buildingTypes"



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [

Example Response
200 OK
Body
Header(6)
View More

{
  "addressFields": {
    "relationships": [
      {
        "id": 3,
        "title": "Building Manager"
      },
      {
        "id": 1,
        "title": "Building Owner"
      },

POST

Find Organisation duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates

This request checks to see if an Organisation which represents this Stakeholder
already exists in Tractivity.

By default the properties used to identify a distinct Organisation are name and
Address Postcode. That is, if the submitted data specifies the same Organisation
located within the same Postcode as an Organisation within Tractivity it is
considered to be the same Organisation.

If the method returns data it is suggested to use the first Organisation
returned, as this is the most recently updated matching Organisation.

If you wish to perform a more detailed duplication check, you can match on the
Organisation data returned in the response body.

If no data is returned then the Organisation does not already exist within
Tractivity.

For more information on this request please see Find Organisation duplicates.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "name": "Doncaster Sheffield Airport"
}



Example Request
Success

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Doncaster Sheffield Airport"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 52,
    "name": "Doncaster Sheffield Airport",
    "telephone": "0114 565845",
    "websiteUrl": "flydsa.co.uk",
    "email": "info@flydsa.co.uk",
    "notes": "",
    "accountHandler": {
      "id": 2122,
      "name": "Arthurs, Jamie"

PUT

Update Organisation (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

If the submitted data was found to match an existing Organisation in Tractivity
in the previous step, update that Organisation with the submitted data.

Take the reponse from the duplication check, and update the properties to have
the submitted values.

Please note that this request overwrites all properties of the existing
Organisation in Tractivity except for Subscription Preferences. The Subscription
Preferences properties will only be overwritten if they are submitted without
the id property.

For more information on this request see Organisations and Update Organisation.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,
        "name": "Stoke, Mark"
    },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,

Example Response
200 OK
Body
Header(3)
No response body
This request doesn't return a response body
POST

Add Organisation (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

If no Organisation matching the submitted data exists within Tractivity create a
new Organisation in Tractivity.

For more information on this request see Organisations and Add Organisation.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"
        },
    "telephone2": "0114 646489",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 54,
  "name": "Tractivity Limited",
  "telephone": "01629 815914",
  "websiteUrl": "tractivity.co.uk",
  "email": "support@tractivity.co.uk",
  "notes": "",
  "accountHandler": {
    "id": 2125,
    "name": "Stoke, Mark"
  },

POST

Find Building duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates

In this example the Stakeholder has submitted their Address.

This request checks to see if the Building already exists within Tractivity.

By default the properties used to identify a distinct Building in Tractivity are
the postcode and building name or number and road.

If there are matching Buildings in Tractivity they will be returned in the
response.

If you wish to perform a more detailed duplication check then you can match on
the data returned in the response to this request.

If no data is returned in the response then the Building does not already exist
within Tractivity.

For more details of this request see Find Building Duplicates.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "postcode": "DE451GT",
    "buildingNameNumberRoad": "systems"
}



Success - no duplicates
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "postcode": "S101HQ",
    "buildingNameNumberRoad": "14"
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Building (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If the Building already exists in Tractivity, update it.

For more details of this request see Buildings and Update Building.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 2079,
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "EnerCom HQ, 12 Carver Street",
    "locality": "",
    "town": "Bakewell",
    "county": "South Yorkshire",
    "country": {
        "id": 232
    },
    "buildingType": {



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 2079,
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "EnerCom HQ, 12 Carver Street",
    "locality": "",
    "town": "Sheffield",
    "county": "South Yorkshire",
    "country": {
        "id": 232

Example Response
200 OK
Body
Header(3)
No response body
This request doesn't return a response body
POST

Add Building (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If no existing Building was found then create a new Building.

For more details of this request see Buildings and Add Building.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
PARAMS
projectID
11
BODYraw
View More

{
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "12 Carver Street",
    "locality": "",
    "town": "Sheffield",
    "county": "South Yorkshire",
    "country": {
        "id": 232
    },
    "buildingType": {
        "id": 2



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '{
    "postcode": "S1 4FS",
    "buildingNameNumberRoad": "12 Carver Street",
    "locality": "",
    "town": {
        "id": 2
    },
    "county": {
        "id": 31

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 2079,
  "postcode": "S1 4FS",
  "buildingNameNumberRoad": "12 Carver Street",
  "locality": "",
  "town": "Sheffield",
  "county": "South Yorkshire",
  "country": {
    "id": 232
  },
  "buildingType": {

POST

Find Organisation Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates

Now that you have the Orgnanisation and Building ids you can create an
Organisation Address.

The Organisation is specified by using the Organisation ID in the request URL.

The Building is specified by the id property of the building in the request
body.

For more information on this request see Find Organisation Address duplicates.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "15",
    "building": {
        "id": 2075
    }
}



Success, no duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "15",
    "building": {
        "id": 2075
    }
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Organisation Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

If an Address already exists for this Organisation then update the Address
provided in the response of the duplication check request.

Set the property "detached" to a value of false to represent a current address.

For more information on this request see Organisation Addresses and Update
Organisation Address.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Organisation Address (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

If there is no Address matching the Organisation to the Building then create a
new one.

Set the property "detached" to a value of false to represent a current address.

For more information on this request see Organisation Addresses and Add
Organisation Address.

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },

Example Response
201 Created
Body
Header(7)
View More

{
  "unitNumber": "Units 15-20",
  "building": {
    "id": 2075,
    "postcode": "Ng18 2HT",
    "buildingNameNumberRoad": "8 Cliff Street",
    "locality": "",
    "town": "Mansfield",
    "county": "Nottinghamshire",
    "country": {
      "id": 232,

POST

Add Organisation Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/54/Activities

In this optional request you create an Organisation Activity which will alert
the Client to take further action.

The Activity is associated to the Organisation we created/updated through the
use of the Organisation's ID in the request URL.

In order to ensure that the Client's chosen Team is alerted, set the Actvity
properties "allocatedToTeams" and "ownerTeams" to contain the Client's chosen
Team.

Set the Start Date and End Date to the date on which the Stakeholder submitted
the data.

For more details of this request see Contact Activity and Add Organisation
Activity

Back to Organisation Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Organisation Registration",
    "activitySubType": {
            "id": 1144
        },
    "status": {
        "id": 1
    },
    "notes": "An Organisation has registered",
    "ownerTeams": [
        {



Create Activity
Example Request
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Contact Newsletter Sign-up",
    "activitySubType": {
            "id": 1028
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has signed-up for a newsletter",

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1934,
  "title": "Contact Newsletter Sign-up",
  "activitySubType": {
    "id": 1028
  },
  "status": {
    "id": 1
  },
  "notes": "A Contact has signed-up for a newsletter",
  "ownerTeams": [

Organisation & Contact registration


DESCRIPTION

This example show you how to use the Tractivity API to add an Organisation with
a linked Contact to a Project in Tractivity. This could be used in the situation
where the Client has tasked you with creating a UI for use by the Client's own
staff who will be talking to Stakeholders and adding them as Contacts to
Tractivity.

The logical steps involved are:

     
 1.  Determining what data is needed before hand.
     
 2.  Fetching the Fields to populate the UI displayed to the end-user.
     
 3.  If address details have been supplied, check to see if the Building already
     exists.
     
 4.  If the Building exists, update it.
     
 5.  If no matching Building exists, create it.
     
 6.  Check to see if the Stakeholder already exists as an Organisation within
     Tractivity.
     
 7.  If a Organisation already exists, update it.
     
 8.  If no appropriate Organisation exists in Tractivity, create an
     Organisation.
     
 9.  Check to see if the Building has already been added to the Organisation as
     an Address.
     
 10. If the Address exists, update it.
     
 11. If the no matching Address exists, create it.
     
 12. Check to see if the Contact already exists in Tractivity.
     
 13. If the Contact already exists, update it.
     
 14. If no appropriate Contact exists then create one.
     
 15. Check to see if the Building has been added to the Contact as an Address
     already within Tractivity.
     
 16. If the Address exists, update it.
     
 17. If the Address does not exist, create it.
     
 18. [Optional] Create an Activity to alert the Client that the Contact has
     registered
     

N.B Subsequent to creating this example we have added a method Organisation,
Contact & Address which can be used to perform steps 3-17 in one request at the
expense of flexibility when determinine what constitutes a duplicate and how to
update them. Please read Organisation, Contact & Address for more information.

DETERMINING WHAT DATA IS NEEDED BEFORE HAND.

This step will largely involve coordinating with the Client who is requesting
this feature. From them you will need to know:

   
 * What Project does the Client want to allow registration for?
   
 * What Building, Organisation and Contact Fields should be available?
   
 * What Teams should have access to the submitted data?
   
 * What properties on an Organisation need to match the submitted data in order
   to consider that Organisation to already exist within Tractivity.
   
 * What properties on a Contact need to match the submitted data in order to
   consider that Contact to already exist within Tractivity.
   
 * Does the Client want an Activity to be created when a Contact signs up?
   
 * If an Activity is to be created, what should the Activity Title be?
   
 * If an Activity is to be created, is this simply for audit purposes, or should
   the Activity also act to alert the Client to take action?
   
 * If an Activity is to be created, and it is to alert the Client, which
   Tractivity Teams should be alerted?
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Authenticate using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

Back to Organisation & Contact Registration.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Example Request
Get Token using Client Credentials

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

GET

Get All Projects - static data


https://acme.tractivity.co.uk/API/V1/Projects

Returns all Projects for the Tractivity System, which can be accessed with your
provided API Credentials.

In this example you will use the ProjectID of 61 as you have already confirmed
with the Tractivity Users that they only wish to use the "South Yorkshire Wind
Turbines" Project.

The Client have confirmed that this will not change so we can store this value
in a configuration file, rather than fetching the data each time the form loads.

If however you decided to present the end-user with a choice of Project, this
response could be cached as it changes infrequently. The cache duration would
depend on how frequently the Client adds Projects. A suggested duration would be
one hour.

For more details of this request see Get All Projects.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

POST

Batch get Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

SUBSCRIPTION STATUSES

The Subscription Status Field values do not change, and therefore can be stored
in a configuration value to reduce the size of requests to the API and improve
performance of the UI.

SUBSCRIPTION METHOD

The Subscription Method is used by the Client to determine how a Stakeholder
recorded their marketing preference. This may be useful to the Client in the
event of a GDPR audit.

In this example the Client has created the Subscription Method of "Registration
Form" (ID 9).

CONTACT PERMISSIONS

In Tractivity the Contact Permission restricts in what ways the Tractivity
system can be used to interact with a Stakeholder.

This is distinct from the Subscription Preference in that Subscription
Preferences specifically refer to Marketing & Mass communications, wheras
Contact Permissions also include how a Stakeholder can be contacted in
one-to-one communications.

For example an Organisation which has a Mailshot Subscription Preferences of
Unsubscribed, and a Contact Permission of Email cannot be sent a Newsletter, but
could be sent an email in response to an Enquiry the Stakeholder has sent to the
Client.

The Contact Permission Fields do not change and so can be stored in a
configuration file to improve the performance of the UI.

For more details of this request see Batch Get Fields.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
		"contactPermissions",
		"subscriptionStatuses",
		"subscriptionMethods"
    ],
	"organisationFieldsToInclude":[
		"contactPermissions",
		"subscriptionStatuses",
		"subscriptionMethods"
	],



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contactFieldsToInclude": [
		"contactPermissions",
		"subscriptionStatuses",
		"subscriptionMethods"
    ],
	"organisationFieldsToInclude":[
		"contactPermissions",
		"subscriptionStatuses",

Example Response
200 OK
Body
Header(6)
View More

{
  "contactFields": {
    "titles": [],
    "suffixes": [],
    "contactPermissions": [
      {
        "id": -1,
        "title": "Email"
      },
      {
        "id": -2,

GET

Get Contact Activity Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams

This request is only required if the Client wants a Contact Activity to be
created.

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

The Field values fetched are Teams, Activity Status and Activity Sub Type.

OWNER TEAMS

Owner Teams in Tractivity donate which Client users are able to edit data within
Tractivity. The Client are able to create and remove Owner Teams, so if they
specify an Owner Team to be used, they must be aware that removing that Team
would cause problems for this form.

In this example the Client has chosen to use a single Owner Team of "South
Yorkshire Wind Farm" (ID 2121). The Client has also determined that the entire
"South Yorkshire Wind Farm" team will be alerted when a Stakeholder is
registered.

It is possible for multiple Owner Teams to be used, and it is possible for the
Client to create additional Owner Teams that they may wish to use.

ACTIVITY STATUS

The Activity Status determines whether or not the Activity requires the Client
to perform an action.
An Activity Status of "Pending" denotes an Activity which requires the Client to
take action.
A "Pending" Activity will be displayed on the Allocated To Team's home page in
Tractivity.
An Activity Status of "Completed" denotes an Activity for which action has
already been taken.
As the Client in this example wants to be alerted to take action use "Pending"
(1).

ACTIVITY SUB TYPE

The Activity Sub Type is used to specify what action the Activity is
recording/prompting. It may be that the Client will create an Activity Sub Type
specifically for your form.
In this example use "Contact Registered" 1039.

For more details of this request see Get Contact Activity Fields.

Back to Contact registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activitySubTypes
include
activityStatuses
include
Teams


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

POST

Batch get Fields - fetch each time


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

This request is used to fetch Fields to display to the Stakeholder when the form
is rendered.

This example requires you to create or update Contacts, Buildings and Contact
Addresses.

As you are selecting fields for multiple Entities use the Batch Fields to select
the Fields for multiple Entities at once.
This will increase performance compared to a request per Entity type.

However these Fields are not often changed and it is likely that the result can
be cached to increase performance. A suggested cache lifetime is 1 hour, it
would be best to discuss any cache lifetime with the Client.

For more details of this request see Batch Get Fields.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [
        "counties",
        "buildingTypes"



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [

Example Response
200 OK
Body
Header(6)
View More

{
  "addressFields": {
    "relationships": [
      {
        "id": 3,
        "title": "Building Manager"
      },
      {
        "id": 1,
        "title": "Building Owner"
      },

POST

Find Building duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates

In this example the Stakeholder has submitted their Address.

This request checks to see if the Building already exists within Tractivity.

By default this check is performed by finding any Buildings with the same
postcode that contain the same Building Name or Number and Road.

For a more detailed check, you will need to the match against the data returned
in the body of the response to this request.

For more details of this request see Find Building Duplicates.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"postcode":"DE451GT",
	"buildingNameNumberRoad":"Systems House"
}



Success - Duplicate found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"postcode":"DE451GT",
	"buildingNameNumberRoad":"Systems House"
}'

Example Response
200 OK
Body
Header(6)
View More

[
  {
    "id": 2080,
    "postcode": "DE451GT",
    "buildingNameNumberRoad": "SYstems House",
    "locality": "",
    "town": "Bakewell",
    "buildingType": {
      "id": 1,
      "title": "Office"
    },

PUT

Update Building (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If the Building already exists in Tractivity, update it.

For more details of this request see Buildings and Update Building.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

[
    {
        "id": 2080,
        "postcode": "DE451GT",
        "buildingNameNumberRoad": "SYstems House",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 1,
            "title": "Office"
        },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '
    {
        "id": 2080,
        "postcode": "DE451GT",
        "buildingNameNumberRoad": "SYstems House",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 1,

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Building (if duplicate not found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If no existing Building was found then create a new Building.

For more details of this request see Buildings and Add Building.

Back to Organisation & Contact Registration.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw


    {
        "postcode": "S101HT",
        "buildingNameNumberRoad": "14",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 6
        }
    }




Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '
    {
        "postcode": "S101HT",
        "buildingNameNumberRoad": "14",
        "locality": "",
        "town": "Bakewell",,
        "buildingType": {
            "id": 6
        }

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2081,
  "postcode": "S101HT",
  "buildingNameNumberRoad": "14",
  "locality": "",
  "town": "Bakewell",
  "buildingType": {
    "id": 6
  },
  "longitude": -1.5059,
  "latitude": 53.3871

POST

Find Organisation duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates

This request checks to see if an Organisation which represents this Stakeholder
already exists in Tractivity.

By default the properties used to identify a distinct Organisation are name and
Address Postcode. That is, if the submitted data specifies the same Organisation
located within the same Postcode as an Organisation within Tractivity it is
considered to be the same Organisation.

If the method returns data it is suggested to use the first Organisation
returned, as this is the most recently updated matching Organisation.

If you wish to perform a more detailed duplication check, you can match on the
Organisation data returned in the response body.

If no data is returned then the Organisation does not already exist within
Tractivity.

For more information on this request please see Find Organisation duplicates.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "name": "Doncaster Sheffield Airport"
}



Example Request
Success

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Doncaster Sheffield Airport"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 52,
    "name": "Doncaster Sheffield Airport",
    "telephone": "0114 565845",
    "websiteUrl": "flydsa.co.uk",
    "email": "info@flydsa.co.uk",
    "notes": "",
    "accountHandler": {
      "id": 2122,
      "name": "Arthurs, Jamie"

PUT

Update Organisation (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

If the submitted data was found to match an existing Organisation in Tractivity
in the previous step, update that Organisation with the submitted data.

Take the reponse from the duplication check, and update the properties to have
the submitted values.

Please note that this request overwrites all properties of the existing
Organisation in Tractivity except for Subscription Preferences. The Subscription
Preferences properties will only be overwritten if they are submitted without
the id property.

For more information on this request see Organisations and Update Organisation.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,
        "name": "Stoke, Mark"
    },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,

Example Response
200 OK
Body
Header(3)
No response body
This request doesn't return a response body
POST

Add Organisation (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

If no Organisation matching the submitted data exists within Tractivity create a
new Organisation in Tractivity.

For more information on this request see Organisations and Add Organisation.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"
        },
    "telephone2": "0114 646489",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 54,
  "name": "Tractivity Limited",
  "telephone": "01629 815914",
  "websiteUrl": "tractivity.co.uk",
  "email": "support@tractivity.co.uk",
  "notes": "",
  "accountHandler": {
    "id": 2125,
    "name": "Stoke, Mark"
  },

POST

Find Organisation Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates

Now that you have the Orgnanisation and Building ids you can create an
Organisation Address.

The Organisation is specified by using the Organisation ID in the request URL.

The Building is specified by the id property of the building in the request
body.

For more information on this request see Find Organisation Address duplicates.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "15",
    "building": {
        "id": 2075
    }
}



Success, duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "1",
    "building": {
        "id": 2075
    }
}'

Example Response
200 OK
Body
Header(6)
View More

[
  {
    "unitNumber": "Units 2-14",
    "building": {
      "id": 2075,
      "postcode": "Ng18 2HT",
      "buildingNameNumberRoad": "8 Cliff Street",
      "locality": "",
      "town": {
        "id": 239,
        "title": "Mansfield"

PUT

Update Organisation Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

If an Address already exists for this Organisation then update the Address
provided in the response of the duplication check request.

Set the property "detached" to a value of false to represent a current address.

For more information on this request see Organisation Addresses and Update
Organisation Address.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Organisation Address (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

If there is no Address matching the Organisation to the Building then create a
new one.

Set the property "detached" to a value of false to represent a current address.

For more information on this request see Organisation Addresses and Add
Organisation Address.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },

Example Response
201 Created
Body
Header(7)
View More

{
  "unitNumber": "Units 15-20",
  "building": {
    "id": 2075,
    "postcode": "Ng18 2HT",
    "buildingNameNumberRoad": "8 Cliff Street",
    "locality": "",
    "town": "Mansfield",
    "county": "Nottinghamshire",
    "country": {
      "id": 232,

POST

Find Contact duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates

You will need to discuss with the Client how to match submitted data with
existing data within Tractivity.

By default in Tractivity the match for a Contact checks on the Contact
firstName, lastName and email. If the Client wishes for more detailed checks
then you will need to check against the data returned in the body of the
response to this request.

For more details of this request see Find Contact duplicates.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"firstName":"Reg",
	"lastName":"Mint",
	"email":"Reg.Mint@anemaildomain.com"
}



Duplicate found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"firstName":"Joseph",
	"lastName":"Northern",
	"email":"j.northern@sheffieldwindturbines.com"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 114,
    "title": {
      "id": 5,
      "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],
    "email": "j.northern@sheffieldwindturbines.com",

PUT

Update Contact (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

Here we are updating the existing Contact with information we have received from
the Stakeholder.

Take the reponse from the duplication check, and update the properties to have
the submitted values.

To link the Contact to the Organisation ensure that the Contact property
"OrganisationIDs" which is an array of int contains the id of the Organisation
which was created/updated.

Please note that this request overwrites all properties of the existing Contact
in Tractivity except for Subscription Preferences. The Subscription Preferences
properties will only be overwritten if they are submitted without the id
property.

For more details of this request see Contacts and Update Contacts.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,
            "name": "Tower, Steven"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

If no duplicate was found then add a new Contact for that Stakeholder.

To link the Contact to the Organisation ensure that the Contact property
"OrganisationIDs" which is an array of int contains the id of the Organisation
which was created/updated.

For more details of this request see Contacts and Add Contacts.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,
            "name": "Tower, Steven"
        },



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 119,
  "title": {
    "id": 5,
    "title": "Mr"
  },
  "firstName": "Joseph",
  "lastName": "Northern",
  "suffixes": [],
  "email": "j.northern@sheffieldwindturbines.com",
  "telephone": "0114 565879",

POST

Find Contact Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Duplicates

Now that you have the Contact and Building ids you can create a Contact Address.

This request checks to see if a matching Contact Address already exists.

For more details of this request see Find Contact Address duplicates.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}



Example Request
No existing address found

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Contact Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses

If an existing Contact Address has been found which matched the submitted
information update it.

As this has been submitted as the Contact's current address, we ensure that the
Detached property is set to false. This indicates that the Address is current.

The Contact against which the Address is created is specified by using the
Contact id in the URL.

For more information on this request see Contact Address and Update Contact
Address.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 2074,
    "unitNumber": "Systems House",
    "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": "Sheffield",
        "county": "South Yorkshire",
        "country": {



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 2074,
    "unitNumber": "Systems House",
    "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": "Sheffield",

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses

If no matching address was found create a new Contact Address.
The Contact against which the Address is created is specified by using the
Contact id in the URL.


For more information on this request see Contact Address and Add Contact
Address.

Back to Organisation & Contact Registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    },
    "relationship":{
    	"id":2
    },
    "DefaultAddress":true,
    "Detached":false
}



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    },
    "relationship":{
    	"id":2
    },
    "DefaultAddress":true,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2073,
  "unitNumber": "Systems House",
  "building": {
    "id": 2074,
    "postcode": "S9 1TL",
    "buildingNameNumberRoad": "Foundary Road",
    "locality": "The Mills",
    "town": {
      "id": 2,
      "title": "Sheffield"

POST

Add Contact Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Activities

In this optional request you create a Contact Activity which will alert the
Client to take further action.

The Activity is associated to the Contact we created/updated through the use of
the Contact's ID in the request URL.

In order to ensure that the Client's chosen Team is alerted, set the Actvity
properties "allocatedToTeams" and "ownerTeams" to contain the Client's chosen
Team.

Set the Start Date and End Date to the date on which the Stakeholder submitted
the data.

For more details of this request see Contact Activity and Add Contact Activity

Back to Organisation and Contact registration.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Contact Registration",
    "activitySubType": {
            "id": 1039
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has registered",
    "ownerTeams": [
        {



Success
Example Request
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Contact Registration",
    "activitySubType": {
            "id": 1039
        },
    "status": {
        "id": 1
    },
    "notes": "A Contact has registered",

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1938,
  "title": "Contact Registration",
  "activitySubType": {
    "id": 1039
  },
  "status": {
    "id": 1
  },
  "notes": "A Contact has registered",
  "ownerTeams": [

Organisation & Contact registration, and submit an Enquiry


DESCRIPTION

This example show you how to use the Tractivity API to add an Organisation with
a linked Contact to a Project in Tractivity and submit to submit Enquiry for
that Contact which the Client will be alerted to.


This could be a form on a website which allows Stakeholders to submit enquiries
about a particular project. This could be used in the situation where the Client
has tasked you with creating a UI for use by the Client's own staff who will be
talking to Stakeholders adding the information into Tractivity.

The logical steps involved are:

     
 1.  Determining what data is needed before hand.
     
 2.  Fetching the Fields to populate the UI displayed to the end-user.
     
 3.  If address details have been supplied, check to see if the Building already
     exists.
     
 4.  If the Building exists, update it.
     
 5.  If no matching Building exists, create it.
     
 6.  Check to see if the Stakeholder already exists as an Organisation within
     Tractivity.
     
 7.  If a Organisation already exists, update it.
     
 8.  If no appropriate Organisation exists in Tractivity, create an
     Organisation.
     
 9.  Check to see if the Building has already been added to the Organisation as
     an Address.
     
 10. If the Address exists, update it.
     
 11. If the no matching Address exists, create it.
     
 12. Check to see if the Contact already exists in Tractivity.
     
 13. If the Contact already exists, update it.
     
 14. If no appropriate Contact exists then create one.
     
 15. Check to see if the Building has been added to the Contact as an Address
     already within Tractivity.
     
 16. If the Address exists, update it.
     
 17. If the Address does not exist, create it.
     
 18. Create an Enquiry.
     
 19. Create an Enquiry Activity, which alerts the Client to respond to the
     Stakeholder.
     

N.B Subsequent to creating this example we have added a method Organisation,
Contact & Address which can be used to perform steps 3-17 in one request at the
expense of flexibility when determinine what constitutes a duplicate and how to
update them. Please read Organisation, Contact & Address for more information.

DETERMINING WHAT DATA IS NEEDED BEFORE HAND.

This step will largely involve coordinating with the Client who is requesting
this feature. From them you will need to know:

   
 * What Project does the Client want to allow registration for?
   
 * What Building, Organisation and Contact Fields should be available?
   
 * What Team(s) should have access to the submitted data?
   
 * What Team(s) should be alerted to respond to the Enquiry.
   
 * What should the Enquiry title be?
   
 * What should the title of the Activity and the Activity Sub Type be?
   
 * What properties on an Organisation need to match the submitted data in order
   to consider that Organisation to already exist within Tractivity.
   
 * What properties on a Contact need to match the submitted data in order to
   consider that Contact to already exist within Tractivity.
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Authenticate using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Example Request
Get Token using Client Credentials

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

GET

Get All Projects


https://acme.tractivity.co.uk/API/V1/Projects

Returns all Projects for the Tractivity System, which can be accessed with your
provided API Credentials.

In this example you will use the ProjectID of 61 as you have already confirmed
with the Tractivity Users that they only wish to use the "South Yorkshire Wind
Turbines" Project.

The Client have confirmed that this will not change so we can store this value
in a configuration file, rather than fetching the data each time the form loads.

If however you decided to present the end-user with a choice of Project, this
response could be cached as it changes infrequently. The cache duration would
depend on how frequently the Client adds Projects. A suggested duration would be
one hour.

For more details of this request see Get All Projects.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 11,
    "title": "North Yorkshire Wind Farm"
  },
  {
    "id": 12,
    "title": "East Midlands Wind Farm"
  },
  {
    "id": 61,

POST

Batch Get Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

This example requires us to create or update Buildings, Contacts, Contact
Addresses, Organisations, Organisation Addresses, Enquiries and Activities.

OWNER TEAMS (ENQUIRIES & ACTIVITIES)

Owner Teams in Tractivity donate which Client users are able to edit data within
Tractivity. The Client are able to create and remove Owner Teams, so if they
specify an Owner Team to be used, they must be aware that removing that Team
would cause problems for this form.

In this example the Client has chosen to use a single Owner Team of "South
Yorkshire Wind Farm" (ID 2121). The Client has also determined that the entire
"South Yorkshire Wind Farm" team will be alerted when a Stakeholder is
registered.

It is possible for multiple Owner Teams to be used, and it is possible for the
Client to create additional Owner Teams that they may wish to use.

SUBSCRIPTION STATUSES (CONTACT & ORGANISATIONS)

The Subscription Status Field values do not change, and therefore can be stored
in a configuration value to reduce the size of requests to the API and improve
performance of the UI.

SUBSCRIPTION METHOD (CONTACT & ORGANISATIONS)

The Subscription Method is used by the Client to determine how a Stakeholder
recorded their marketing preference. This may be useful to the Client in the
event of a GDPR audit.

In this example the Client has created the Subscription Method of "Registration
Form" (ID 9).

CONTACT PERMISSIONS (BUILDINGS, CONTACTS, ORGANISATIONS, ENQUIRIES & ACTIVITIES)

In Tractivity the Contact Permission restricts in what ways the Tractivity
system can be used to interact with a Stakeholder.

This is distinct from the Subscription Preference in that Subscription
Preferences specifically refer to Marketing & Mass communications, wheras
Contact Permissions also include how a Stakeholder can be contacted in
one-to-one communications.

For example an Organisation which has a Mailshot Subscription Preferences of
Unsubscribed, and a Contact Permission of Email cannot be sent a Newsletter, but
could be sent an email in response to an Enquiry the Stakeholder has sent to the
Client.

The Contact Permission Fields do not change and so can be stored in a
configuration file to improve the performance of the UI.

ENQUIRY STATUSES

The Enquiry Status values do not change.
In this example we use the Field "Live" (3) for an Enquiry which needs requires
a response.
The Field "Closed" (6) would be used for an Enquiry which has already been
responded to and requires no further action.

ENQUIRY MADE VIA

The enquiryMadeVia property on an Enquiry descriptions how the Enquiry was
brought to the attention of the Client.
In this example the Client may create an Enquiry Made Via Field specifically to
represent the form you are creating.

ACTIVITY STATUS

The Activity Status determines whether or not the Activity requires the Client
to perform an action.
An Activity Status of "Pending" denotes an Activity which requires the Client to
take action. A "Pending" Activity will be displayed on the Allocated To Team's
home page in Tractivity.
An Activity Status of "Completed" denotes an Activity for which action has
already been taken.
As the Client in this example wants to be alerted to take action use "Pending"
(1).

For more details of this request see Batch Get Fields.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
		"contactPermissions",
		"subscriptionStatuses",
		"subscriptionMethods"
    ],
	"organisationFieldsToInclude":[
		"contactPermissions",
		"subscriptionStatuses",
		"subscriptionMethods"
	],



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contactFieldsToInclude": [
        "ownerTeams",
		"contactPermissions",
		"subscriptionStatuses",
		"subscriptionMethods"
    ],
	"organisationFieldsToInclude":[
		"ownerTeams",

Example Response
200 OK
Body
Header(6)
View More

{
  "activityFields": {
    "statuses": [
      {
        "id": 2,
        "title": "Completed"
      },
      {
        "id": 1,
        "title": "Pending"
      }

GET

Get Enquiry Activity Fields - static data


https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/0/Activities/Fields?include=activitySubTypes

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

In this request we fetch the Enquiry Activity sub types.
This field is not currently supported in the Batch get Fields method.


For more information on this request see Get Enquiry Activity fields.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activitySubTypes


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Enquiries/0/Activities/Fields?include=activitySubTypes'

Example Response
200 OK
Body
Header(6)
View More

{
  "activitySubTypes": [
    {
      "title": "Callback",
      "id": 1071
    },
    {
      "title": "Email Invitation Sent",
      "id": -6
    },
    {

POST

Batch Get Fields - fetch each time


https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields

This request is used to fetch Fields to display to the Stakeholder when the form
is rendered.

This example requires you to create or update Contacts, Buildings and Contact
Addresses.

As you are selecting fields for multiple Entities use the Batch Fields to select
the Fields for multiple Entities at once.
This will increase performance compared to a request per Entity type.

However these Fields are not often changed and it is likely that the result can
be cached to increase performance. A suggested cache lifetime is 1 hour, it
would be best to discuss any cache lifetime with the Client.

For more details of this request see Batch Get Fields.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [
        "towns",
        "counties",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Batch/Fields' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contactFieldsToInclude": [
        "titles",
        "genders",
        "stakeholderCategories",
        "accountHandlers",
        "ageRanges"
    ],
    "buildingFieldsToInclude": [

Example Response
200 OK
Body
Header(6)
View More

{
  "addressFields": {
    "relationships": [
      {
        "id": 3,
        "title": "Building Manager"
      },
      {
        "id": 1,
        "title": "Building Owner"
      },

POST

Find Building duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates

In this example the Stakeholder has submitted their Address.

This request checks to see if the Building already exists within Tractivity.

By default this check is performed by finding any Buildings with the same
postcode that contain the same Building Name or Number and Road.

For a more detailed check, you will need to the match against the data returned
in the body of the response to this request.

For more details of this request see Find Building Duplicates.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"postcode":"DE451GT",
	"buildingNameNumberRoad":"Systems House"
}



Success - no duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"postcode":"S101hQ",
	"buildingNameNumberRoad":"14"
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Building (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If the Building already exists in Tractivity, update it.

For more details of this request see Buildings and Update Building.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

[
    {
        "id": 2080,
        "postcode": "DE451GT",
        "buildingNameNumberRoad": "SYstems House",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 1,
            "title": "Office"
        },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '
    {
        "id": 2080,
        "postcode": "DE451GT",
        "buildingNameNumberRoad": "SYstems House",
        "locality": "",
        "town": {
            "id": 1,
            "title": "Bakewell"

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Building (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings

If no existing Building was found then create a new Building.

For more details of this request see Buildings and Add Building.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More


    {
        "postcode": "S101HT",
        "buildingNameNumberRoad": "14",
        "locality": "",
        "town": "Bakewell",
        "buildingType": {
            "id": 6
        },
	    "projects":[{
	        "id": 11,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Buildings' \
--header 'Content-Type: application/json' \
--data-raw '
    {
        "postcode": "S101HT",
        "buildingNameNumberRoad": "14",
        "locality": "",
        "town": {
            "id": 2
        },
        "buildingType": {

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2081,
  "postcode": "S101HT",
  "buildingNameNumberRoad": "14",
  "locality": "",
  "town": "Bakewell",
  "buildingType": {
    "id": 6
  },
  "longitude": -1.5059,
  "latitude": 53.3871,

POST

Find Organisation duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates

This request checks to see if an Organisation which represents this Stakeholder
already exists in Tractivity.

By default the properties used to identify a distinct Organisation are name and
Address Postcode. That is, if the submitted data specifies the same Organisation
located within the same Postcode as an Organisation within Tractivity it is
considered to be the same Organisation.

If the method returns data it is suggested to use the first Organisation
returned, as this is the most recently updated matching Organisation.

If you wish to perform a more detailed duplication check, you can match on the
Organisation data returned in the response body.

If no data is returned then the Organisation does not already exist within
Tractivity.

For more information on this request please see Find Organisation duplicates.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "name": "Doncaster Sheffield Airport"
}



Example Request
Success

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Doncaster Sheffield Airport"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 52,
    "name": "Doncaster Sheffield Airport",
    "telephone": "0114 565845",
    "websiteUrl": "flydsa.co.uk",
    "email": "info@flydsa.co.uk",
    "notes": "",
    "accountHandler": {
      "id": 2122,
      "name": "Arthurs, Jamie"

PUT

Update Organisation (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

If the submitted data was found to match an existing Organisation in Tractivity
in the previous step, update that Organisation with the submitted data.

Take the reponse from the duplication check, and update the properties to have
the submitted values.

Please note that this request overwrites all properties of the existing
Organisation in Tractivity except for Subscription Preferences. The Subscription
Preferences properties will only be overwritten if they are submitted without
the id property.

For more information on this request see Organisations and Update Organisation.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,
        "name": "Stoke, Mark"
    },



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 54,
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "This Organisation is being updated in this request",
    "accountHandler": {
        "id": 2125,

Example Response
200 OK
Body
Header(3)
No response body
This request doesn't return a response body
POST

Add Organisation (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations

If no Organisation matching the submitted data exists within Tractivity create a
new Organisation in Tractivity.

For more information on this request see Organisations and Add Organisation.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
            "id": 2125,
            "name": "Stoke, Mark"
        },
    "telephone2": "0114 646489",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Tractivity Limited",
    "telephone": "01629 815914",
    "websiteUrl": "tractivity.co.uk",
    "email": "support@tractivity.co.uk",
    "notes": "",
    "accountHandler": {
        "id": 2125,
        "name": "Stoke, Mark"

Example Response
201 Created
Body
Header(4)
View More

{
  "id": 54,
  "name": "Tractivity Limited",
  "telephone": "01629 815914",
  "websiteUrl": "tractivity.co.uk",
  "email": "support@tractivity.co.uk",
  "notes": "",
  "accountHandler": {
    "id": 2125,
    "name": "Stoke, Mark"
  },

POST

Find Organisation Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates

Now that you have the Orgnanisation and Building ids you can create an
Organisation Address.

The Organisation is specified by using the Organisation ID in the request URL.

The Building is specified by the id property of the building in the request
body.

For more information on this request see Find Organisation Address duplicates.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "15",
    "building": {
        "id": 2075
    }
}



Success, duplicates found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "1",
    "building": {
        "id": 2075
    }
}'

Example Response
200 OK
Body
Header(6)
View More

[
  {
    "unitNumber": "Units 2-14",
    "building": {
      "id": 2075,
      "postcode": "Ng18 2HT",
      "buildingNameNumberRoad": "8 Cliff Street",
      "locality": "",
      "town": "Mansfield",
      "county": "Nottinghamshire",
      "country": {

PUT

Update Organisation Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

If an Address already exists for this Organisation then update the Address
provided in the response of the duplication check request.

Set the property "detached" to a value of false to represent a current address.

For more information on this request see Organisation Addresses and Update
Organisation Address.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
            "id": 2,
            "title": "Tenant"
        },

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Organisation Address (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses

If there is no Address matching the Organisation to the Building then create a
new one.

Set the property "detached" to a value of false to represent a current address.

For more information on this request see Organisation Addresses and Add
Organisation Address.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },
    "startDate": "2019-02-19",
    "detached": false,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations/51/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Units 15-20",
    "building": {
        "id": 2075
    },
    "relationship": {
        "id": 1,
        "title": "Building Owner"
    },

Example Response
201 Created
Body
Header(7)
View More

{
  "unitNumber": "Units 15-20",
  "building": {
    "id": 2075,
    "postcode": "Ng18 2HT",
    "buildingNameNumberRoad": "8 Cliff Street",
    "locality": "",
    "town": "Mansfield",
    "county": "Nottinghamshire",
    "country": {
      "id": 232,

POST

Find Contact duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates

You will need to discuss with the Client how to match submitted data with
existing data within Tractivity.

By default in Tractivity the match for a Contact checks on the Contact
firstName, lastName and email. If the Client wishes for more detailed checks
then you will need to check against the data returned in the body of the
response to this request.

For more details of this request see Find Contact duplicates.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
	"firstName":"Reg",
	"lastName":"Mint",
	"email":"Reg.Mint@anemaildomain.com"
}



Duplicate found
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
	"firstName":"Joseph",
	"lastName":"Northern",
	"email":"j.northern@sheffieldwindturbines.com"
}'

Example Response
200 OK
Body
Header(3)
View More

[
  {
    "id": 114,
    "title": {
      "id": 5,
      "title": "Mr"
    },
    "firstName": "Joseph",
    "lastName": "Northern",
    "suffixes": [],
    "email": "j.northern@sheffieldwindturbines.com",

PUT

Update Contact (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

Here we are updating the existing Contact with information we have received from
the Stakeholder.

Take the reponse from the duplication check, and update the properties to have
the submitted values.

To link the Contact to the Organisation ensure that the Contact property
"OrganisationIDs" which is an array of int contains the id of the Organisation
which was created/updated.

Please note that this request overwrites all properties of the existing Contact
in Tractivity except for Subscription Preferences. The Subscription Preferences
properties will only be overwritten if they are submitted without the id
property.

For more details of this request see Contacts and Update Contacts.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,
            "name": "Tower, Steven"



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "id": 114,
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts

If no duplicate was found then add a new Contact for that Stakeholder.

To link the Contact to the Organisation ensure that the Contact property
"OrganisationIDs" which is an array of int contains the id of the Organisation
which was created/updated.

For more details of this request see Contacts and Add Contacts.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,
            "name": "Tower, Steven"
        },



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts' \
--header 'Content-Type: application/json' \
--data-raw '{
        "title": {
            "id": 5,
            "title": "Mr"
        },
        "firstName": "Joseph",
        "lastName": "Northern",
        "accountHandler":{
            "id": 2124,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 119,
  "title": {
    "id": 5,
    "title": "Mr"
  },
  "firstName": "Joseph",
  "lastName": "Northern",
  "suffixes": [],
  "email": "j.northern@sheffieldwindturbines.com",
  "telephone": "0114 565879",

POST

Find Contact Address duplicates


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses/Duplicates

Now that you have the Contact and Building ids you can create a Contact Address.

This request checks to see if a matching Contact Address already exists.

For more details of this request see Find Contact Address duplicates.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}



Example Request
No existing address found

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses/Duplicates' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    }
}'

Example Response
200 OK
Body
Header(6)

[]

PUT

Update Contact Address (if duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses

If an existing Contact Address has been found which matched the submitted
information update it.

As this has been submitted as the Contact's current address, we ensure that the
Detached property is set to false. This indicates that the Address is current.

The Contact against which the Address is created is specified by using the
Contact id in the URL.

For more information on this request see Contact Address and Update Contact
Address.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 2074,
    "unitNumber": "Systems House",
    "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": "Sheffield",
        "county":  "South Yorkshire",
        "country": {



Example Request
Success
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/114/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 2074,
    "unitNumber": "Systems House",
    "building": {
        "id": 2074,
        "postcode": "S9 1TL",
        "buildingNameNumberRoad": "Foundary Road",
        "locality": "The Mills",
        "town": "Sheffield",

Example Response
200 OK
Body
Header(5)
No response body
This request doesn't return a response body
POST

Add Contact Address (if no duplicate found)


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses

If no matching address was found create a new Contact Address.
The Contact against which the Address is created is specified by using the
Contact id in the URL.


For more information on this request see Contact Address and Add Contact
Address.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    },
    "relationship":{
    	"id":2
    },
    "DefaultAddress":true,
    "Detached":false
}



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/119/Addresses' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unitNumber": "Systems House",
    "building": {
        "id": 2074
    },
    "relationship":{
    	"id":2
    },
    "DefaultAddress":true,

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 2073,
  "unitNumber": "Systems House",
  "building": {
    "id": 2074,
    "postcode": "S9 1TL",
    "buildingNameNumberRoad": "Foundary Road",
    "locality": "The Mills",
    "town": {
      "id": 2,
      "title": "Sheffield"

POST

Add Enquiry


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries

This step creates an Enquiry.

You do not perform duplication checks on Enquiries.

The Enquiry can only be created after the Contact has been created.

Populate the Enquiry properties with the data submitted by the Stakeholder and
the static data provided by the Client.

The Enquiry is linked to the Contact through the use of the Contact ID in the
request URL.

For an Enquiry which requires action set the status to "Live". For an Enquiry
which has already been responded to and is being added solely for audit
purposes, use the status of "Closed".
In this example where an Enquiry is being submitted to the Client for the first
time,set the Enquiry status to Live.

You can optionally link the Enquiry to the Organisation through setting the
Enquiry property "AssociatedOrganisationID" to be the id of the Organisation.

If the Enquiry is about the provided Address or Building then you can link the
Enquiry to the Contact Address by setting the Enquiry property
"contactAddressIDs" to contain the id of the Contact Address added or updated
earlier in the process.

For more information on this request see Enquiries and Add Enquiry.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Request for information",
    "associatedOrganisationID": 53,
    "subProjects": [
        {
            "id": 226,
            "title": "Construction"
        }
    ],
    "stakeholderCategory":  {
            "id": 4,



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/117/Enquiries' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Request for information",
    "associatedOrganisationID": 53,
    "subProjects": [
        {
            "id": 226,
            "title": "Construction"
        }
    ],

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1032,
  "title": "Request for information",
  "contactID": 117,
  "associatedOrganisationID": 53,
  "subProjects": [
    {
      "id": 226,
      "title": "Construction"
    }
  ],

POST

Add Enquiry Activity


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities

Activities are created to represent actions which the Client has taken or must
take.

In this example the Client must take action to respond to the Stakeholder's
Enquiry.

Create an Enquiry Activity with a status of "Pending".
Set the ownerTeams and the allocatedToTeams to include the Team(s) within
Tractivity which will respond to the Enquiry.

This will create an Activity which will appear on the Client's home screen
within Tractivity prompting them to respond to the Enquiry.

The Enquiry is specified by using the Enquiry id in the request URL.

For more information on this request see Enquiry Activity and Add Enquiry
Activity.

Back to Organisation & Contact Registration, and submit an Enquiry.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"
    },
    "notes": "call about last meeting",



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/115/Enquiries/1031/Activities' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title": "Phone call",
    "activitySubType": {
            "title": "Phone Call",
            "id": -4
        },
    "status": {
        "id": 1,
        "title": "Pending"

Example Response
201 Created
Body
Header(7)
View More

{
  "id": 1932,
  "associatedContactIDs": [],
  "title": "Phone call",
  "activitySubType": {
    "id": -4,
    "title": "Phone Call"
  },
  "status": {
    "id": 1,
    "title": "Pending"

Events


DESCRIPTION

This example describes the process for displaying Events on a website for the
public to browse.


DISCUSSION WITH THE CLIENT

Before you start development there are some questions which can only be answered
by the Client which you need to know.

There are several questions which can only be answered by the Client, for which
you will need to know the answer in order to start development.

   
 * Will you be displaying the Events for a single Project or multiple Projects?
   
 * Which Project or Projects should the Events be displayed for?
   
 * Determine whether or not Events should be displayed based on the Event
   property displayOnWebsite.
     
   * This relates to the Display on Website setting when viewing or editing an
     Event in Tractivity.
     
   * This field may not be enabled in Tractivity for all Projects.
     
   
 * When adding a Contact what criteria do we use to determine if the Contact is
   a duplicate Contact to be updated?
     
   * For example do we match solely on email address, or email address and name,
     or name and Building postcode etc.
     
   
 * When updating a Contact who already exists in the system what are the rules
   for updating the properties
     
   * For instance if the existing Contact has a telephone number and the new
     Contact has a different telephone number, which number is to be kept?
     
   
 * Should an Activity be created representing the registration?
   
 * If an Activity is created should this alert any individuals or teams?
   

For the purposes of this example we are assuming the following answers:

   
 * We will be displaying Events for a single Project - ID 48, Derbyshire API
   Construction.
   
 * We will only display Events with a displayOnWebsite value of 'true'.
   
 * We will consider a Contact to be a duplicate based on email address and last
   name.
   
 * We will not overwrite any fields on the existing Contact. We will add any new
   information the new Contact provides which the existing Contact does not
   have.
   
 * We will create an Activity.
   
 * This Activity will be created to alert the Derbyshire API Construction team
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Static Data

Static Data are Fields which can be fetched a single time at the start of
development, but can be considered to be consistent thereafter and will not need
to be fetched each time the Website is run. These are values which either cannot
be edited, or can only be edited by a Tractivity System Administrator. Instead
we would suggest storing the required values in a configuration value.

As a general rule for Static data it would be advisible to check that the the
values are the same on the Live Tractivity site as they are on the Stage
Tractivity. As these systems run on different databases the Ids may be
different. It is also advisable to ensure that the Client's Tractivity System
Administrator is aware of this Static data so that they will know the
consequences of changing this data.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

GET

Get All Projects


https://acme.tractivity.co.uk/API/V1/Projects

The Client has specified that we will only be interested in the "Derbyshire API
Construction" Project. We will note down the Id 48 and store it in a
configuration file.

For more details of this request see Get All Projects.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get All Projects

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects'

Example Response
200 OK
Body
Header(6)
View More

[
  {
    "id": 48,
    "title": "Derbyshire API Construction"
  },
  {
    "id": 12,
    "title": "Nuclear Project"
  },
  {
    "id": 45,

GET

Get Event Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Fields?include=eventStatuses

Only the Event Status Field can be considered Static. It also does not change
between Stage and Live systems and cannot be edited by the Tractivity System
Administrator.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
eventStatuses

[Optional] The name of a Field type to return the Fields for



Example Request
Get Event Fields - Statuses

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Fields?include=eventStatuses'

Example Response
200 OK
Body
Header(6)
View More

{
  "eventCategories": [],
  "subProjects": [],
  "eventStatuses": [
    {
      "id": 1,
      "title": "Completed"
    },
    {
      "id": 2,
      "title": "Cancelled"

GET

Get Invited Contact Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/26/InvitedContacts/Fields

We shall only be adding Contacts to an Event as Confirmed, and so will only need
to store the id 2 in configuration.

Similar to the eventStatus this field will not change between Stage and Live
systems, and cannot be altered by a Tractivity System Administrator.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
eventInvitationStatuses

[Optional] The name of a Field type to return the Fields for



Example Request
Get Event Registration Fields

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/26/InvitedContacts/Fields'

Example Response
200 OK
Body
Header(6)
View More

{
  "eventInvitationStatuses": [
    {
      "id": 3,
      "title": "Awaiting Confirmation"
    },
    {
      "id": 4,
      "title": "Awaiting Invitation"
    },
    {

GET

Get Contact Fields


https://acme.tractivity.co.uk/API/V1/Projects/48/Contacts/Fields?include=ownerTeams&include=subscriptionStatuses&include=subscriptionMethods

These values will be used when creating or updating a Contact who is registering
for an event.

OWNER TEAMS

In this example the Client has chosen to use a single Owner Team of "Derbyshire
API Construction" (ID 2457).

SUBSCRIPTION STATUSES

If you are providing the user the option to sign up to receive infomation about
further events or other marketing communication then you will need all of these
values.

SUBSCRIPTION METHOD

In this example we shall use the method "Website" (ID 2)

For more details of this request see Get Contact Fields.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
ownerTeams
include
subscriptionStatuses
include
subscriptionMethods


Example Request
Get Contact Fields

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/48/Contacts/Fields?include=ownerTeams&include=subscriptionStatuses&include=subscriptionMethods'

GET

Get Contact Activity Fields


https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams

This request is only required if the Client wants an Event Activity to be
created.

This request returns fields whose values are not determined at run time but are
instead determined by the Client in the design phase.
As such this request would not be run each time the UI was built.
It may be that the Client will at some point change these values so we would
recommend storing these values in an easily updatable format such as a
configuration file or database rather than hard-coding them.

The Field values fetched are Teams, Activity Status and Activity Sub Type.

Use the same value for Team as we use for the Contacts- "Derbyshire API
Construction" (2457).

The Activity Status determines whether or not the Activity requires the Client
to perform an action.
An Activity Status of "Pending" denotes an Activity which requires the Client to
take action.
A "Pending" Activity will be displayed on the Allocated To Team's home page in
Tractivity.
An Activity Status of "Completed" denotes an Activity for which action has
already been taken.
As the Client in this example wants to be alerted to take action use "Pending"
(1).

The Activity Sub Type is used to specify what action the Activity is
recording/prompting. It may be that the Client will create an Activity Sub Type
specifically for your form.
In this example use "Contact Registered" 1039.

For more details of this request see Get Contact Activity Fields.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
PARAMS
include
activitySubTypes
include
activityStatuses
include
Teams


Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Contacts/0/Activities/Fields?include=activitySubTypes&include=activityStatuses&include=Teams'

Example Response
200 OK
Body
Header(6)
View More

{
  "activityStatuses": [
    {
      "title": "Completed",
      "id": 2
    },
    {
      "title": "Pending",
      "id": 1
    }
  ],

Display Events


DESCRIPTION

This example describes the process for displaying Events on a website for the
public to browse. This will involve the following steps:

    
 1. Searching for the Events.
    
 2. Displaying Event details.
    


DISCUSSION WITH THE CLIENT

There are several questions which can only be answered by the Client, for which
you will need to know the answer in order to start development.

   
 * Will you be displaying the Events for a single Project or multiple Projects?
   
 * Which Project or Projects should the Events be displayed for?
   
 * Determine whether or not Events should be displayed based on the Event
   property displayOnWebsite.
     
   * This relates to the Display on Website setting when viewing or editing an
     Event in Tractivity.
     
   * This field may not be enabled in Tractivity for all Projects.
     
   

For the purposes of this example we are assuming the following answers:

   
 * We will be displaying Events for a single Project - ID 48, Derbyshire API
   Construction.
   
 * We will only display Events with a displayOnWebsite value of 'true'.
   

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Get Token using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Example Request
Get Token using Client Credentials

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--header 'Authorization: Basic ODI2MDg0ZDgtNzZkOS3434TQ0LTk4NGMtYjI2YTllNTQ5YTl9OkptaHElZSlnRUkycF3dLWhaWUx2QS1XNg==' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

POST

Get all Events


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Search

We are searching for all Events in the Derbyshire API Construction Project,
which occur within a given month and have been set to Display on website.

As such the URL contains the Derbyshire API Construction Project ID, and the
other requirements are set in the body of the request.

This request is using the default page size of 15 events. If pageCount property
of the response is greater than 1 then you will need to make further requests to
fetch all events.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
PARAMS
pageIndex
0
pageSize
100
BODYraw

{
    "IsDisplayedOnWebsite":"true",
    "dateFrom":"2020-02-01T00:00:00",
    "dateTo":"2020-03-01T00:00:00"
}



Get all Events in Februray, which should be visible on a public website
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/Search' \
--header 'Content-Type: application/json' \
--data-raw '{
    "IsDisplayedOnWebsite":"true",
    "dateFrom":"2020-02-01T00:00:00",
    "dateTo":"2020-03-01T00:00:00"
}'

Example Response
200 OK
Body
Header(6)
View More

{
  "pageCount": 1,
  "results": [
    {
      "id": 57,
      "eventId": 57,
      "title": "Public Exhibition",
      "eventStartDate": "2020-02-25T09:00:00",
      "eventEndDate": "2020-02-25T16:30:00",
      "eventOverview": "",
      "allowRegistration": true,

Display an Event in detail

When a user selects an Event from the Calendar we need to show the full Event
details. This can be acomplished with a single Get Event request.

If the Event has allowRegistration set to true and there is no venueCapacity, or
the venueCapacity is greater than the numberOfConfirmedInvitees then we will
make the option of registering for the event available.

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Get Token using Client Credentials


https://acme.tractivity.co.uk/API/V1/token

Use the API Credentials which the Client has provided you to authenticate with
the API.

For more details see Get Token using Client Credentials.

Back to Contact Registration.

AUTHORIZATIONBasic Auth
Username
c820f470-e0ba-46f8-9687-2a83a90b270d
Password
MySecret
BODYraw

grant_type=client_credentials



Get Token using Client Credentials
Example Request

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/token' \
--data-raw 'grant_type=client_credentials'

Example Response
200 OK
Body
Header(8)

{
  "access_token": "a28f444a-677d-4b36-ab16-90cdac8e59ca",
  "token_type": "bearer",
  "expires_in": 1199
}

GET

Get Event


https://acme.tractivity.co.uk/API/V1/Projects/61/Events/57

The request URL is in the format
"{RootURL}/Projects/{ProjectID}/Events/{EventID}/"

Where the ProjectID is the ID of the Project to select data for and the EventID
is the ID of the Event.

Fetches a single Event.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Get Event

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/61/Events/57'

Example Response
200 OK
Body
Header(6)
View More

{
  "id": 57,
  "title": "Public Exhibition",
  "eventStartDate": "2020-02-25T09:00:00",
  "eventEndDate": "2020-02-25T16:30:00",
  "allowRegistration": true,
  "isDisplayedOnWebsite": true,
  "eventCategory": {
    "id": 17,
    "title": "Exhibition"
  },

Add Invited Contact

Registering a Contact will involve the following steps.

    
 1. Authenticate
    
 2. Fetch the Contact Fields required to build the form, and display the form to
    the user.
    
 3. When the user submits the form check to see if a duplicate Contact already
    exists in the system
      
    * If a duplicate Contact exists then update that Contact.
      
    * If no duplicate Contact exists then add a new Contact.
      
    
 4. Add the Contact as an InvitedContact to the Event.
    
 5. If the Contact has already registered then warn the User.
    
 6. If the Event has reached capacity then warn the User.
    
 7. If adding the InvitedContact was successful then add a Contact Activity.
    

For Step 1 Authentication see API Structure/Authentication/Get Token using
Client Credentials
For Steps 2, 3 and 7 see the example detailing the requests involved in creating
a Contact and a Contact Activity can be found at Examples/Contact registration.
Steps 4-6 - Adding the Contact to the Event can be achieved through API
Structure/Projects/Events/InvitedContacts/Add Invited Contact"

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API


Project Sharing - Organisation

This example demonstrates how to add an Organisation to a Project, then share
that Organisation to a different Project and update the Project-specific data
for that Organisation

AUTHORIZATIONOAuth 2.0
This folder is using OAuth 2.0 from collectionTractivity API

POST

Add Organisation


https://acme.tractivity.co.uk/API/V1/Projects/11/Organisations

Here we are initally adding an Organisation to a Project.

Note that if you do not supply any values to the "project" property the
Organisation is only made available to the current Project as specified by the
project ID in the URL.

It is possible to add an Organisation to a Project and share that Organisation
in a single request by adding multiple Projects to the "Projects" property. In
this example we are performing the share in a subsequent update to more clearly
demonstrate the seperation of Project-specific properties.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "name": "Transport for London",
    "email": "contact@tfl.co.uk",
    "telephone": "02060125486",
    "organisationsCategories": [
        {
            "id": 136,
            "title": "Transport",
            "organisationSubCategories": []
        }
    ],



Example Request
Success
View More

curl --location --request POST 'https://acme.tractivity.co.uk/API/V1/Projects/61/Organisations' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Transport for London",
    "email": "contact@tfl.co.uk",
    "telephone": "02060125486",
    "organisationsCategories": [
        {
            "id": 136,
            "title": "Transport",
            "organisationSubCategories": []

Example Response
201 Created
Body
Header(6)
View More

{
  "id": 82,
  "name": "Transport for London",
  "telephone": "02060125486",
  "email": "contact@tfl.co.uk",
  "contactPermitted": [],
  "stakeholderCategories": [
    {
      "id": 1,
      "title": "statutory Stakeholder"
    }

PUT

Update Organisation - Share with Project 27


https://acme.tractivity.co.uk/API/V1/Projects/11/Organisations/

In this step we are updating the Organisation with one change - adding
additional Projects to the "projects" property.

This will make the Organisation available in Project 27

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 82,
    "name": "Transport for London",
    "telephone": "02060125486",
    "email": "contact@tfl.co.uk",
    "contactPermitted": [],
    "stakeholderCategories": [
    	{
    		"id":1,
    		"title":"statutory Stakeholder"
    	}



Example Request
Update Organisation - Share with Project 27
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/11/Organisations/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 82,
    "name": "Transport for London",
    "telephone": "02060125486",
    "email": "contact@tfl.co.uk",
    "contactPermitted": [],
    "stakeholderCategories": [
    	{
    		"id":1,

GET

Get organisation - Project 27


https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/82

Now that the Organisation has been shared with Project 27 we can get that
Organisation from Project 27.

You can see that Project-specific properties such as "stakeholderCategories" and
"newsletterSubscriptionPreference" do not have the same values as in Project 11.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/82'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 82,
  "name": "Transport for London",
  "telephone": "02060125486",
  "websiteUrl": "",
  "email": "contact@tfl.co.uk",
  "notes": "",
  "linkedInUrl": "",
  "twitterUrl": "",
  "facebookUrl": "",
  "youtubeUrl": "",

PUT

Update Organisation - Project 27


https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/

Here we update the Organisation in Project 27. We change the Telephone and
Stakeholder Category.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API
HEADERS
Content-Type
application/json
BODYraw
View More

{
    "id": 82,
    "name": "Transport for London",
    "telephone": "0206 264 546",
    "websiteUrl": "",
    "email": "contact@tfl.co.uk",
    "notes": "",
    "linkedInUrl": "",
    "twitterUrl": "",
    "facebookUrl": "",
    "youtubeUrl": "",



Example Request
Update Organisation - Project 27
View More

curl --location --request PUT 'https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 82,
    "name": "Transport for London",
    "telephone": "0206 264 546",
    "websiteUrl": "",
    "email": "contact@tfl.co.uk",
    "notes": "",
    "linkedInUrl": "",
    "twitterUrl": "",

GET

Get organisation - Project 27


https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/82

Now that the Organisation has been shared with Project 27 we can get that
Organisation from Project 27.

You can see that Project-specific properties such as "stakeholderCategories" and
"newsletterSubscriptionPreference" do not have the same values as in Project 11.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/82'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 82,
  "name": "Transport for London",
  "telephone": "0206 264 546",
  "websiteUrl": "",
  "email": "contact@tfl.co.uk",
  "notes": "",
  "linkedInUrl": "",
  "twitterUrl": "",
  "facebookUrl": "",
  "youtubeUrl": "",

GET

Get organisation - Project 11


https://acme.tractivity.co.uk/API/V1/Projects/11/Organisations/82

Getting the Organisation from Project 11 we can see that the Telephone number
has been updated based on the previous update to the Organisation in Project 27.

However the changes to the Project-specific fields Stakeholder Categories and
Subscription Preferences have only been made in Project 27.

AUTHORIZATIONOAuth 2.0
This request is using OAuth 2.0 from collectionTractivity API



Example Request
Success

curl --location --request GET 'https://acme.tractivity.co.uk/API/V1/Projects/27/Organisations/82'

Example Response
200 OK
Body
Header(5)
View More

{
  "id": 82,
  "name": "Transport for London",
  "telephone": "0206 264 546",
  "websiteUrl": "",
  "email": "contact@tfl.co.uk",
  "notes": "",
  "linkedInUrl": "",
  "twitterUrl": "",
  "facebookUrl": "",
  "youtubeUrl": "",
apidocumentation.tractivity.co.uk Open in urlscan Pro 3.215.255.119 Public Scan

Form analysis 0 forms found in the DOM

Text Content

apidocumentation.tractivity.co.uk Open in urlscan Pro
3.215.255.119 Public Scan

Form analysis
0 forms found in the DOM
