contact API

Follow

Summary

Requirements

All API calls require a dedicated JSON Web Token (JWT). These are created when a user with a dedicated mobile resource logs in to the application. If you are using the API for programmatic queries, it is best to create a dedicated user for the JWT as this gets reset each time the user logs in.

Endpoint

rest/contact/contact

POST

Adds new contact data, or updates existing contacts in the system based on contact reference and client ID provided

File Format Spec

 

List of Included Fields
Field Name Data Type Mandatory? Description Updatable?
clientRef Text (50) Yes The ref of the client in Oneserve No
contactRef Text (50) Yes A unique reference for the contact No
salutation Text (50) Yes The contact salutation in Oneserve Yes
forename Text (80) Yes The contact forename Yes
surname Text (80) Yes The contact surname Yes
contact1 Text (80) Yes Contact 1 details. Yes
contact1Type Integer Yes Contact 1 type Id. Must match one of the pre-configured types. Yes
contact2 Text (50) No Contact 2 details. Yes
contact2Type Integer No Contact 2 type Id. Must match one of the pre-configured types. Yes
contact3 Text (80) No Contact 3 details. Yes
contact3Type Integer No Contact 3 type Id. Must match one of the pre-configured types. Yes
contact4 Text (80) No Contact 4 details. Yes
contact4Type Integer No Contact 4 type Id. Must match one of the pre-configured types. Yes
preferredContact Integer Yes Number of the preferred contact: 1 - 4. Yes
address1 Text (200) Yes Address line 1 for the contact Yes
address2 Text (200) Yes Address line 2 for the contact Yes
address3 Text (200) No Address line 3 for the contact Yes
address4 Text (200) No Address line 4 for the contact Yes
postCode Text (50) Yes Postcode for the contact Yes
notes Text (2000) No The contact notes field in Oneserve Yes
considerations Text (4000) No The contact considerations field in Oneserve Yes
locations Array No Multiple occurences of this record for each location that this contact is associated to.  
location Ref Text (50) Yes The location reference to associate this contact to. Yes
isPreferred Boolean Yes Indicates whether this is the preferred contact for this location. Yes
startDate Date No Date from which the contact is valid Yes
endDate Date No Date to which the contact is valid Yes
usageTypeId Integer No Usage Type Id of the Location. Will update the Usage Type on the Location if present.
Must match an existing usage type ID in the system
Yes

 

Request Representations

 

Example JSON Payload
{
    "clientRef": "29",
    "contactRef": "ZARADILLO1",
    "salutation": "Mr",
    "forename": "John",
    "surname": "Test",
    "contact1": "",
    "contact1Type": "1",
    "contact2": "07123456789",
    "contact2Type": "10",
    "contact3": "test@test.test",
    "contact3Type": "6",
    "contact4": "",
    "contact4Type": "1",
    "preferredContact": "1",
    "address1": "Address line 1",
    "address2": "Address line 2",
    "address3": "Address line 3",
    "address4": "Address line 4",
    "notes": "These are notes",
    "considerations": "These are considerations",
    "postCode": "EX49HL",
    "locations": [
        {
            "locationRef": "10174",
            "isPreferred": "True",
            "startDate": "09/07/2019",
            "endDate": "18/12/2019",
            "usageTypeId": "1"
        }
    ]
}

 

Available Response Representations

HTTP Code Description Schema
200 Contact(s) Posted Success Message
400 Bad Request Error
401 Unauthorized Error
403 Forbidden Error
404 Address Not Found Error
405 Method Not Allowed Error
415 Unsupported Media Type Error
500 Internal Server Error Error

Example Success Response

{
    "result" : "success",
    "result_msg" : ""
}

Troubleshooting

 

401 Unauthorized

Response

401 Unauthorized

Reason

This error occurs if the OS_REST_AUTH_TOKEN has not been provided, has expired, or does not exist in the system

Resolution

Verify your OS_REST_AUTH_TOKEN with support

403 Forbidden

Response

403 Forbidden

Reason

This error indicates that something is blocking your connection to the server

Resolution

Open a ticket with the support team with details of your connection so that your access can be verfied

404 Not Found

Response

404 Not Found

Reason

This error should only occur if the endpoint has been mistyped in some way, which will lead the call to an endpoint that does not exist

Resolution

Verify the endpoint matches the value specified in this article

405 Method Not Allowed

Response

405 Method Not Allowed

Reason

This error will occur if an unacceptable method has been used in the call such as GET or DELETE

Resolution

Ensure that you are using a POST call to this endpoint

415 Unsupported Media Type

Response

415 Unsupported Media Type

Reason

This response is given if data is passed to the endpoint in a format other than application/json

Resolution

Pass your requests as a JSON object with the application/json header

REST0002

Response

{
    "result": "fail",
    "result_msg": "REST0002",
    "result_error_msg": "A JSONObject text must begin with '{' at character..."
}

Reason

This error occurs if you have tried to pass a call that isn't wrapped as a JSON object. For example:

[
    {
        "clientRef": "29",
        ...
    }
]

Resolution

Ensure that all calls are valid JSON objects following a similar layout to the example call above

Transaction rolled back because it has been marked as rollback-only

Response

{
    "result": "fail",
    "result_msg": "Transaction rolled back because it has been marked as rollback-only"
}

Reason

This is a generic server error which usually indicates that a field is of the wrong type or is overlong, which causes a failure to insert the data into the database

Resolution

Ensure that all fields are filled out according to the field data types listed above

Could not execute statement

Response

{
    "result": "fail",
    "result_msg": "could not execute statement; SQL [n/a]; nested exception is org.hibernate.exception.DataException: could not execute statement"
}

Reason

This is a generic server error which usually indicates that a field is of the wrong type or is overlong, which causes a failure to insert the data into the database

Resolution

Ensure that all fields are filled out according to the field data types listed above

Unable to locate client ref supplied

Response

{
    "result": "fail",
    "result_msg": "Unable to locate client ref supplied"
}

Reason

This error is returned when a client with the provided ID cannot be found in the system

Resolution

Ensure that the client exists in Oneserve and that all fields are filled out according to the field data types listed above