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 systemYes
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
This error occurs if the Verify your This error indicates that something is blocking your connection to the server Open a ticket with the support team with details of your connection so that your access can be verfied 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 Verify the endpoint matches the value specified in this article This error will occur if an unacceptable method has been used in the call such as Ensure that you are using a This response is given if data is passed to the endpoint in a format other than Pass your requests as a JSON object with the This error occurs if you have tried to pass a call that isn't wrapped as a JSON object. For example: Ensure that all calls are valid JSON objects following a similar layout to the example call above 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 Ensure that all fields are filled out according to the field data types listed above 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 Ensure that all fields are filled out according to the field data types listed above This error is returned when a client with the provided ID cannot be found in the system Ensure that the client exists in Oneserve and that all fields are filled out according to the field data types listed above401 Unauthorized
Response
401 Unauthorized
Reason
OS_REST_AUTH_TOKEN
has not been provided, has expired, or does not exist in the systemResolution
OS_REST_AUTH_TOKEN
with support403 Forbidden
Response
403 Forbidden
Reason
Resolution
404 Not Found
Response
404 Not Found
Reason
Resolution
405 Method Not Allowed
Response
405 Method Not Allowed
Reason
GET
or DELETE
Resolution
POST
call to this endpoint415 Unsupported Media Type
Response
415 Unsupported Media Type
Reason
application/json
Resolution
application/json
headerREST0002
Response
{
"result": "fail",
"result_msg": "REST0002",
"result_error_msg": "A JSONObject text must begin with '{' at character..."
}
Reason
[
{
"clientRef": "29",
...
}
]
Resolution
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
Resolution
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
Resolution
Unable to locate client ref supplied
Response
{
"result": "fail",
"result_msg": "Unable to locate client ref supplied"
}
Reason
Resolution