Expected Locations

Note: This page has not yet been converted to the new developer portal format. Please use Swagger to test this API.

Expected Locations

Data Model

Expected Location Object

Field	Mandatory	Type	Description
id	Yes	long	The ID of the Expected Location
contactId	Yes if contactIDType=id	long	The ID of the contact
contactExternalId	Yes if contactIDType=externalId	long	The external ID of the contact
address	Yes	Address Object	Address
travelCategory	No, the field is only readable	String	Domestic/International or Local/Non-Local
travelType	No, the field is only readable	String	Departure/Arrival/Transit

Address Object

Field	Mandatory	Type	Description
arriveDate	Yes	date	Expected date of arrival
expireDate	Yes	date	Expected date of departure
assetExternalId	No	string	The external ID of the asset
iata	No	string	IATA code
locationName	No	string	The name of the location
suite	No	string
streetAddress	No	string
city	No	string
state	No	string
postalCode	No	string	ZIP code
country	No	string
gisLocation	No	GIS Location Object

GIS Location Object

Field	Mandatory	Type	Default Value	Description
lat	Yes	double		Latitude
lon	Yes	double		Longitude

POST /expectedLocations/{orgId}?contactIdType={idType}

Description

Create expected locations for a contact.

URL

/expectedLocations/{organizationId}?contactIdType={idType}

Method

POST

URL Parameters

Parameter	Mandatory	Type	Default Value	Description
organizationId	Yes	integer		Organization ID
idType	No	string	id	◊ id - Contact ID ◊ externalId - Contact External ID
returnIds	No	boolean	false	If included, create expected locations ID in the response.

NOTE: The batch creation expected locations API call has the following limitations, per API call:
◊ 1,000 expected locations for creation when not geocoded.
◊ 10,000 expected locations for creation when geoccoded or attached to an IATA code or an existing building.

Request Body

Request Body
1 Link contact(s) to asset(s). [{ "contactId": 1234567890123, "address": { "assetExternalId": "Apple-Park", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } }, { "contactId": 9876543210987, "address": { "assetExternalId": "Apple-Campus", "arriveDate": "2018-01-01T01:00:00Z", "expireDate": "2018-12-31T23:00:00Z" } } ]
1.1 Link contact(s) to asset(s) using contact external ID. [{ "contactExternalId": "[email protected]", "address": { "assetExternalId": "Apple-Park", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } }, { "contactExternalId": "[email protected]", "address": { "assetExternalId": "Apple-Campus", "arriveDate": "2018-01-01T01:00:00Z", "expireDate": "2018-12-31T23:00:00Z" } }]
2 Link contact(s) to airport(s) or railway station(s) based on the IATA code. [{ "contactId": 1234567890123, "address": { "iata": "SFO", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" } }, { "contactId": 9876543210987, "address": { "iata": "PEK", "arriveDate": "2018-02-03T22:00:00Z", "expireDate": "2018-02-04T06:00:00Z" } }]
3 Link contact (s) to new address(es). [{ "contactId": 1234567890123, "address": { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } }, { "contactId": 9876543210987, "address": { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States", "arriveDate": "2018-01-01T01:00:00Z", "expireDate": "2018-12-31T23:00:00Z" } }]
4 Link contact(s) to different types of address(es). [{ "contactId": 1234567890123, "address": { "assetExternalId": "Apple-Park", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } }, { "contactId": 9876543210987, "address": { "iata": "PEK", "arriveDate": "2018-02-03T22:00:00Z", "expireDate": "2018-02-04T06:00:00Z" } }, { "contactId": 9876543210987, "address": { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States", "arriveDate": "2018-01-01T01:00:00Z", "expireDate": "2018-12-31T23:00:00Z" } }]

Responses

Code	Response
200	◊ The expected locations are all updated correctly and the returnIds parameter is set to false. { "message": "OK", "code": 100 } ◊ The expected locations are partially updated correctly and the returnIds parameter is set to true. { "message": "OK", "code": 100, "data": [ "23455" "23456" ] } { "message": "OK", "code": 200, "data": [ "Contact 1234567890123 not found", "23456" ] } ◊ The expected locations are partially updated and the returnIds parameter is set to true. { "message": "OK", "code": 200, "data": [ "Contact 1234567890123 not found", "23456" ] } ◊ The expected locations failed to update. { "message": "OK", "code": 300, "data": [ "The [1] Invalid AssetExternalId." ] }
401	◊ Invalid credentials. { "status": 401, "message": "Invalid credentials: Password invalid" } ◊ Invalid organization or user does not have access to the organization. { "status": 401, "message": "Org 123 not accessible to this user, or does not exist." }

Code

Response

200

◊ The expected locations are all updated correctly and the returnIds parameter is set to false.
{
"message": "OK",
"code": 100
}
◊ The expected locations are partially updated correctly and the returnIds parameter is set to true.
{
"message": "OK",
"code": 100,
"data": [
"23455"
"23456"
]
}

{
"message": "OK",
"code": 200,
"data": [
"Contact 1234567890123 not found",
"23456"
]
}

◊ The expected locations are partially updated and the returnIds parameter is set to true.
{
"message": "OK",
"code": 200,
"data": [
"Contact 1234567890123 not found",
"23456"
]
}

◊ The expected locations failed to update.
{
"message": "OK",
"code": 300,
"data": [
"The [1] Invalid AssetExternalId."
]
}

401

◊ Invalid credentials.
{
"status": 401,
"message": "Invalid credentials: Password invalid"
}
◊ Invalid organization or user does not have access to the organization.
{
"status": 401,
"message": "Org 123 not accessible to this user, or does not exist."
}

POST /expectedLocations/{organizationId}/{contactId}?contactIdType={idType}

Description

Create a new expected location.

URL

/expectedLocations/{organizationId}{contactId}?contactIdType={idType}

Method

POST

Requeequest HstHeader

Parameter	Mandatory	Description
Authorization	Yes	Authorization

URL Parameters

Parameter	Mandatory	Description
organizationId	Yes	Organization ID
contactId	Yes	contactId
contactIdType	No	The ID used to identify contact. ◊ id - Contact ID ◊ externalId - Contact External ID

Request Body

Request Body
1 Link contact(s) expected location(s) to asset(s). { "assetExternalId": "BJ", "arriveDate": "2018-07-27T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" }
2 Link contact(s) expected location(s) to airport(s) or railway station(s) base on IATA code. { "iata": "SFO", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" }
3 Link contact(s) expected location(s) to new address(es). { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" }

Responses

Code	Response
200 OK	◊ Response Successfully. The expected locations are all created correctly. { "message": "OK", "id": 470595271655441, "baseUri": " /expectedLocations/1328214341321438/28161671063234", "instanceUri":"/expectedLocations/1328214341321438/281616710632347/470595271655441" }
400 Bad Request	◊ Contact ID is not long number when the contactIdType is id. RequestBody: URL: /expectedLocations/1328214341321438/ contact_test?contactIdType=id ResponseBody: { "status": 400, "message": "Invalid contact ID, contact_test." } ◊ Organization id is not long number. RequestBody: URL: /expectedLocations/1328214341321438organization_test/523123213 ResponseBody: { "status": 400, "message": "Type mismatch exception." } ◊ Invalid AssetExternalId RequestBody: NOTE: The assetExternald is correct. { "assetExternalId": "SH", "arriveDate": "2018-07-27T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } ResponseBody: { "status": 400, "message": "Invalid assetExternalId." } RequestBody: NOTE: The assetExternalId is empty. { "assetExternalId": "", "arriveDate": "2018-07-27T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } ResponseBody: { "status": 400, "message": "The streetAddress can not be blank." }
	◊ Invalid Iata RequestBody: NOTE: The IATA ID is incorrect. { "iata": "SFO-TEST", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" } ResponseBody: { "status": 400, "message": "Invalid iata." } RequestBody: NOTE: The IATA ID is empty. { "iata": "", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" } ResponseBody: { "status": 400, "message": "The streetAddress can not be blank." } ◊ RequestBody is Empty RequestBody: { } ResponseBody: { "status": 400, "message": "The streetAddress can not be blank." } ◊ Validation Failed RequestBody: { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States" }
	ResponseBody: { "status": 400, "message": "date is null" } NOTE: The other fields are the same. If the locationName is missing, the message of the response body will be “The locationName cannot be blank”.
401 Unauthorized	◊ Require REST API Access. { "status": 401, "message": "User does not have API permissions for this method" } ◊ User has no access to the organization. RequestBody: URL: /expectedLocations/1328214341320709/444206992588829 user is org1-test2 ResponseBody: { "status": 401, "message": "Org 1328214341320709 not accessible to this user, or does not exist." } ◊ Contact is not in a group that is accessible to its group leader. RequestBody: URL: tracyDev2_gm ResponseBody: { "status": 401, "message": "Contact is not in a group accessible to this group leader." }
404 Request Not Found	◊ Resource not found. RequestBody: URL: /expectedLocations/1328214341321438/281616710632345 ResponseBody: { "status": 404, "message": "Contact (ID = 281616710632345) is not found." } RequestBody: URL: /expectedLocations/123456789/281616710632345 ResponseBody: { "status": 404, "message": "organization (ID = 123456789) is not found." }

GET /expectedLocations/{organizationId}/{contactId}?contactIdType={idType}

Description

Get Expected Locations.

URL

/expectedLocations/{organizationId}/{contactId}?contactIdType={idType}

Method

GET

Request Header

Parameter	Mandatory	Description
Authorization	Yes	Authorization

URL Parameters

Parameter	Mandatory	Description
organizationId	Yes	Organization ID
contactId	Yes	contactId
contactIdType	No	The ID used to identify the contact. ◊ id - Contact ID ◊ externalId - Contact External ID

Responses

Code	Response
200 OK	◊ Response Successfully. { "message": "OK", "result": [ { "id": 470595271655436, "contactId": 281616710632347, "contactExternalId": "[email protected]", "address": { "streetAddress": "1 Apple Park Way", "state": "California", "locationName": "Work", "gisLocation": { "lon": -121.372550464062, "lat": 38.3967340305652 }, "country": "United States", "city": "Cupertino", "locationId": 0, "arriveDate": 1517603400000, "expireDate": 1535617800000, "locationSource": "Api", "locationSourceId": 0 } }, { "id": 470595271655440, "contactId": 281616710632347, "contactExternalId": "[email protected]", "address": { "streetAddress": "San Francisco International Apt", "state": "CA", "locationName": "San Francisco International Apt", "gisLocation": { "lon": -122.39166666666668, "lat": 37.61888888888889
	}, "country": "US", "city": "San Francisco", "locationId": 0, "iata": "SFO", "arriveDate": 1517574600000, "expireDate": 1535589000000, "locationSource": "Api", "locationSourceId": 0 } }, { "id": 470595271655441, "contactId": 281616710632347, "contactExternalId": "[email protected]", "address": { "streetAddress": "中国北京市东城区东四十条甲22号", "state": "CN", "locationName": "Location Name 5_Beijing", "suite": "8", "gisLocation": { "lon": 116.4250339, "lat": 39.9336332 }, "country": "CN", "city": "I", "locationId": 4402341478405, "assetExternalId": "BJ", "arriveDate": 1532723400000, "expireDate": 1535617800000, "locationSource": "Api", "locationSourceId": 0 } } ] }
400 Bad Request	◊ Contact ID is not long number when the contactIdType is id. RequestBody: URL: /expectedLocations/1328214341321438/ contact_test?contactIdType=id ResponseBody: { "status": 400, "message": "Invalid contact ID, contact_test." } ◊ Organization id is not long number. RequestBody: URL: /expectedLocations/1328214341321438organization_test/523123213 ResponseBody: { "status": 400, "message": "Type mismatch exception." }
401 Unauthorized	◊ Require REST API Access. { "status": 401, "message": "User does not have API permissions for this method" } ◊ User has no access to the organization. RequestBody: URL: /expectedLocations/1328214341320709/444206992588829 user is org1-test2 ResponseBody: { "status": 401, "message": "Org 1328214341320709 not accessible to this user, or does not exist." } ◊ Contact is not in a group that is accessible to its group leader. RequestBody: URL: tracyDev2_gm ResponseBody: { "status": 401, "message": "Contact is not in a group accessible to this group leader." }
404 Not Found	◊ Resource not found. RequestBody: URL: /expectedLocations/1328214341321438/281616710632345 ResponseBody: { "status": 404, "message": "Contact (ID = 281616710632345) is not found." } RequestBody: URL: /expectedLocations/123456789/281616710632345 ResponseBody: { "status": 404, "message": "organization (ID = 123456789) is not found." }

GET /expectedLocations/{organizationId}/{contactId}/{expectedLocationId}?contactIdType={idType}

Description

Get an Expected Location by Expected Location ID.

URL

/expectedLocations/{organizationId}/{contactId}/{expectedLocationId}?contactIdType={idType}

Method

GET

Request Header

Parameter	Mandatory	Description
Authorization	Yes	Authorization

URL Parameters

Parameter	Mandatory	Description
organizationId	Yes	Organization ID
contactId	Yes	contactId
expectedLocationId	Yes	expectedLoctionId
contactIdType	No	The ID used to identify the contact. ◊ id - Contact ID ◊ externalId - Contact External ID

Responses

Code	Response
200 OK	◊ Response Successfully. { "message": "OK", "result": { "id": 470595271655440, "contactId": 281616710632347, "contactExternalId": "[email protected]", "address": { "streetAddress": "San Francisco International Apt", "state": "CA", "locationName": "San Francisco International Apt", "gisLocation": { "lon": -122.39166666666668, "lat": 37.61888888888889 }, "country": "US", "city": "San Francisco", "locationId": 0, "iata": "SFO", "arriveDate": 1517603400000, "expireDate": 1535617800000, "locationSource": "Api", "locationSourceId": 0 } } } NOTE: If we create a new address when we save an expected location,m the fields “assetExternalId” and “iata” will not be displayed.
400 Bad Request	◊ Contact ID is not long number when the contactIdType is id. RequestBody: URL: /expectedLocations/1328214341321438/ contact_test?contactIdType=id ResponseBody: { "status": 400, "message": "Invalid contact ID, contact_test." } ◊ Organization id is not long number. RequestBody: URL: /expectedLocations/1328214341321438organization_test/523123213 ResponseBody: { "status": 400, "message": "Type mismatch exception." }
401 Unauthorized	◊ Require REST API Access { "status": 401, "message": "User does not have API permissions for this method" } ◊ User has no access to the organization. RequestBody: URL: /expectedLocations/1328214341320709/444206992588829 user is org1-test2 ResponseBody: { "status": 401, "message": "Org 1328214341320709 not accessible to this user, or does not exist." } ◊ Contact is not in a group that is accessible to its group leader. RequestBody: URL: tracyDev2_gm ResponseBody: { "status": 401, "message": "Contact is not in a group accessible to this group leader." }
404 Not Found	◊ Resource not found. RequestBody: URL: /expectedLocations/1328214341321438/281616710632345 ResponseBody: { "status": 404, "message": "Contact (ID = 281616710632345) is not found." } RequestBody: URL: /expectedLocations/123456789/281616710632345 ResponseBody: { "status": 404, "message": "organization (ID = 123456789) is not found." }

PUT /expectedLocations/{organizationId}/{contactId}/{expectedLocationId}?contactIdType={idType}

Description

Updte an expected location.

URL

/expectedLocations/{organizationId}/{contactId}/{expectedLocationId}?contactIdType={idType}

Method

PUT

Request Header

Parameter	Mandatory	Description
Authorization	Yes	Authorization

URL Parameters

Parameter	Mandatory	Description
organizationId	Yes	Organization ID
contactId	Yes	contactId
expectedLocationId	Yes	expectedLocation ID
contactIdType	No	The ID used to identify contact. ◊ id - Contact ID ◊ externalId - Contact External ID

Request Body

Request Body
1 Update in the case of the Link contact(s) expected location(s) to asset(s). { "assetExternalId": "SUBWAY STATION", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" }
2 Update in the case of the link contact(s) expected location(s) to airport(s) or railway station(s) based on IATA code. { "iata": "SFO", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" }
3 Update in the case of the link contact(s) expected location(s) to new address(es). { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" }

Responses

Code	Response
200 OK	◊ Response Successfully. { "message": "OK", "id": 470595271655440, "baseUri": " /expectedLocations/1328214341321438/281616710632347/47059527165544", "instanceUri":"/expectedLocations/1328214341321438/281616710632347/470595271655440" }
400 Bad Request	◊ Contact ID is not long number when the contactIdType is id. RequestBody: URL: /expectedLocations/1328214341321438/ contact_test?contactIdType=id ResponseBody: { "status": 400, "message": "Invalid contact ID, contact_test." } ◊ Organization id is not long number. RequestBody: URL: /expectedLocations/1328214341321438organization_test/523123213 ResponseBody: { "status": 400, "message": "Type mismatch exception." } ◊ Invalid AssetExternalId RequestBody: NOTE: The assetExternald is correct. { "assetExternalId": "SH", "arriveDate": "2018-07-27T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } ResponseBody: { "status": 400, "message": "Invalid assetExternalId." } RequestBody: NOTE: The assetExternalId is empty. { "assetExternalId": "", "arriveDate": "2018-07-27T20:30:00Z", "expireDate": "2018-08-30T08:30:00Z" } ResponseBody: { "status": 400, "message": "The streetAddress can not be blank." }
	◊ Invalid Iata RequestBody: NOTE: The IATA ID is incorrect. { "iata": "SFO-TEST", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" } ResponseBody: { "status": 400, "message": "Invalid iata." } RequestBody: NOTE: The IATA ID is empty. { "iata": "", "arriveDate": "2018-02-02T20:30:00Z", "expireDate": "2018-02-03T08:00:00Z" } ResponseBody: { "status": 400, "message": "The streetAddress can not be blank." } ◊ RequestBody is Empty RequestBody: { } ResponseBody: { "status": 400, "message": "The streetAddress can not be blank." } ◊ Validation Failed RequestBody: { "locationName": "Work", "streetAddress": "1 Apple Park Way", "city": "Cupertino", "state": "California", "country": "United States" }
	ResponseBody: { "status": 400, "message": "date is null" } NOTE: The other fields are the same. If the locationName is missing, the message of the response body will be “The locationName cannot be blank”.
401 Unauthorized	◊ Require REST API Access. { "status": 401, "message": "User does not have API permissions for this method" } ◊ User has no access to the organization. RequestBody: URL: /expectedLocations/1328214341320709/444206992588829 user is org1-test2 ResponseBody: { "status": 401, "message": "Org 1328214341320709 not accessible to this user, or does not exist." } ◊ Contact is not in a group that is accessible to its group leader. RequestBody: URL: tracyDev2_gm ResponseBody: { "status": 401, "message": "Contact is not in a group accessible to this group leader." }
404 Request Not Found	◊ Resource not found. RequestBody: URL: /expectedLocations/1328214341321438/281616710632345 ResponseBody: { "status": 404, "message": "Contact (ID = 281616710632345) is not found." } RequestBody: URL: /expectedLocations/1328214341321438/281616710632347/47059527165542712 RequestBody: URL: /expectedLocations/123456789/281616710632345 ResponseBody: { "status": 404, "message": "The expected location (ID = 47059527165542712) of contact (ID = 281616710632347) is not found." } ResponseBody: { "status": 404, "message": "organization (ID = 123456789) is not found." }

DELETE /expectedLocations/{organizationId}/{contactId}/{expectedLocationId}?contactIdType={idType}

Description

Delete Expected Locations.

URL

/expectedLocations/{organizationId}/{contactId}/{expectedLocationId}?contactIdType={idType}

Method

DELETE

Request Header

Parameter	Mandatory	Description
Authorization	Yes	Authorization

URL Parameters

Parameter	Mandatory	Description
organizationId	Yes	Organization ID
contactId	Yes	contactId
expectedLocationId	Yes	expectedLocation ID
contactIdType	No	The ID used to identify the contact. ◊ id - Contact ID ◊ externalId - Contact External ID

Responses

Code	Response
200 OK	◊ Response Successfully. { "message": "OK" }
400 Bad Request	◊ Contact ID is not long number when the contactIdType is id. RequestBody: URL: /expectedLocations/1328214341321438/ contact_test?contactIdType=id ResponseBody: { "status": 400, "message": "Invalid contact ID, contact_test." } ◊ Organization id is not long number. RequestBody: URL: /expectedLocations/1328214341321438organization_test/523123213 ResponseBody: { "status": 400, "message": "Type mismatch exception." }
401 Unauthorized	◊ Require REST API Access. { "status": 401, "message": "User does not have API permissions for this method" } ◊ User has no access to the organization. RequestBody: URL: /expectedLocations/1328214341320709/444206992588829 user is org1-test2 ResponseBody: { "status": 401, "message": "Org 1328214341320709 not accessible to this user, or does not exist." } ◊ Contact is not in a group that is accessible to its group leader. RequestBody: URL: tracyDev2_gm ResponseBody: { "status": 401, "message": "Contact is not in a group accessible to this group leader." }
404 Not Found	◊ Resource not found. RequestBody: URL: /expectedLocations/1328214341321438/281616710632345/470595271655427 ResponseBody: { "status": 404, "message": "Contact (ID = 281616710632345) is not found." } RequestBody: URL: /expectedLocations/1328214341321438/281616710632347/47059527165542712 { "status": 404, "message": "The expected location (ID = 47059527165542712) of contact (ID = 281616710632347) is not found." } RequestBody: URL: /expectedLocations/1328214341321438/281616710632347/47059527165542712 ResponseBody: { "status": 404, "message": "organization (ID = 123456789) is not found." }

DELETE /expectedLocations/{organizationId}/batch

Description

Batch Delete ExpectedLocations.

URL

/expectedLocations/{organizationId}/batch

Method

DELETE

Request Header

Parameter	Mandatory	Description
Authorization	Yes	Authorization

URL Parameters

Parameter	Mandatory	Type	Default Value	Description
organizationId	Yes			Organization ID

NOTE: The Delete Expected Location API call has the following limitation:
◊ 50,000 expected locations for deletion per API call.

Responses

Code	Response	Model
200 OK	◊ Response Successfully. { "message": "OK", "code": 100 } ◊ Partially Successfully. { "message": "OK", "code": 200, "data": [ "241901148045321: Not found." ] } ◊ All failed. { "message": "OK", "code": 300, "data": [ "241901148045320: Not found.", "241901148045321: Not found." ] }	RestfulBatchOperationResult
400 Bad Request		RestfulBatchOperationResult
401 Unauthorized	◊ Deletee ExpectedLocations - Response Body. { "status": 401, "message": "Invalid credentials: Get User failed" }	AuthenticationException