Action

An Action is a pickup, delivery, visit or any other transaction event being performed by the User.

The Action object

Property Type Description
id uuid string Unique identifier for the object
user JSON The user object to which the action was assigned
type string The type of action, can be pickup, delivery, dropoff, visit, stopover or task
lookup_id string An identifier for the action that can based on your internal ids
assigned_at ISO datetime string The time at which the action was assigned to the user
scheduled_at ISO datetime string The scheduled time by when the action should be completed
expected_place JSON The place object where the action is to be completed
status string The action status. Can be created, assigned, started, completed, canceled, suspended (automatically by HyperTrack if it is not completed or canceled for a long time)
sub_status string Granular action status. Can be not_started, in_queue (for assigned status) leaving_now, on_the_way, arriving, arrived (for started status)
initial_eta ISO datetime string The initial eta calculated for the action
eta ISO datetime string The current eta for the action, calculated in real-time
completed_place JSON The place where the action was completed
completed_at ISO datetime string The time at which the action was completed
suspended_at ISO datetime string The time at which the action was suspended, if it was suspended instead of being completed
canceled_at ISO datetime string The time at which the action was canceled, if it was canceled
tracking_url string The URL at which this action can be tracked. This URL can be shared with anyone
created_at ISO datetime string Timestamp of when action was created
modified_at ISO datetime string Timestamp of when action was modified
display JSON Imp details for user for an action that has been assigned or started like duration_remaining and distance_remaining
event_flags JSON array List of unexpected events that have been generated for this action. Each event has fields type and value. Here is the list of all event types. Example of this property: [{ type: "action.completed_late", value: 58321 }, { type: "action.completed_at_different_place_than_expected", value: 1256 }]. Time value is in seconds and distance in meters
metadata JSON Metadata about the action that may be useful for you to see when an action is tracked

Create an Action

Creates a new action object.

HTTP Request

POST https://api.hypertrack.com/api/v1/actions/

Returns

Returns an action object if the call succeeded.

Parameters

Parameter Required Description
expected_place No The Place object where the action will be performed. Only one of expected_place or expected_place_id must be specified.
expected_place_id No The id of the Place where the action will be performed. This parameter can be used instead of expected_place, if your users are going to perform actions at a place very frequently. So instead of sending address (in a Place object) every time you create an action, you can (1)create a Place one time, (2)store the id of the Place object you get in response and (3)send this id every time you create an action
scheduled_at No The scheduled time by when the action should be completed
type No The type of the action, possible values are pickup, delivery, dropoff, visit, stopover or task. Defaults to task.
lookup_id No An id that you can specify based on your internal ids
user_id No This assigns the action to a User. It has the same effect as Assign Action to a User API below
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"expected_place\": {\"address\": \"2200 Sand Hill Road Menlo Park CA USA\"}, \"scheduled_at\": \"2016-03-09T07:00:00.00Z\"}" \
     https://api.hypertrack.com/api/v1/actions/
place = {'address': "2200 Sand Hill Road Menlo Park CA USA"}
hypertrack.Action.create(
    expected_place=place,
    scheduled_at='2016-03-09T07:00:00.00Z'
)
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Map<String, Object> place = new HashMap<>();
place.put("address", "2200 Sand Hill Road Menlo Park CA USA")
Map<String, Object> params = new HashMap<>();
params.put("expected_place", place);
params.put("scheduled_at", "2016-03-09T07:00:00.00Z");
Action action = actionFactory.create(params);
place = Hash.new()
place['address'] = '2200 Sand Hill Road Menlo Park CA USA'
HyperTrack::Action.create(expected_place: place,
                          scheduled_at: '2016-03-09T07:00:00.00Z')

Assign Actions to a User

This API will assign a list of Action objects to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<id>/assign_actions/

Returns

Returns a User object to which the actions are added.

Parameters

Parameter Required Description
action_ids Yes List of action ids to be assigned to the user
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"action_ids\": [\"6daacb03-6f02-4c60-b084-e9ffcd9eaf56\", \"37ae09b4-4801-48cb-bc50-99a7ee53f257\"]}" \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/assign_actions/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.assign_actions(action_ids=['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257'])
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");

List<String> actionIds = Arrays.asList("6daacb03-6f02-4c60-b084-e9ffcd9eaf56", "37ae09b4-4801-48cb-bc50-99a7ee53f257");
userFactory.assignActions(user, actionIds);
user = HyperTrack::User.retrieve(user_id)
user.assign_actions({action_ids: ['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257']})

Complete an Action

Completes an Action.

[warning] Completing actions

If marking actions is done using interactions in the mobile app, it is recommended to use the SDK methods for completing actions. This way the action has the right metadata for more accurate data collection.

HTTP Request

POST https://api.hypertrack.com/api/v1/actions/<id>/complete/

Returns

Returns an action object if the call succeeded.

Parameters

Parameter Required Description
completed_at No Timestamp when action is completed, default to current time
completion_location No Location at which action is completed
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/complete/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.complete()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.complete(action, null);
action = HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.complete()

Cancel Action

Cancels an Action. Canceled actions cannot be reassigned, removed or completed.

HTTP Request

POST https://api.hypertrack.com/api/v1/actions/<id>/cancel/

Returns

Returns an action object if the call succeeded.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/cancel/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.cancel()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.cancel(action, null);
action = HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.cancel()

Retrieve an Action

Retrieves an action object with the id.

HTTP Request

GET https://api.hypertrack.com/api/v1/actions/<id>/

Returns

Returns an action object if the call succeeded.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')

Update an action

Edit an existing action object.

HTTP Request

PATCH https://api.hypertrack.com/api/v1/actions/<id>/

Returns

Returns the updated action object.

Parameters

Parameter Required Description
type string The type of action, can be pickup, delivery, dropoff, visit, stopover, trip or task
lookup_id string An identifier for the action that can based on your internal ids
scheduled_at ISO datetime string The scheduled time by when the action should be completed
expected_place JSON The place object where the action is to be completed
metadata JSON Metadata about the action that may be useful for you to see when an action is tracked
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"type\": \"pickup\", \"lookup_id\": \"CRN1234\"}" \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
action = hypertrack.Action.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
action.type = 'pickup'
action.lookup_id = 'CRN1234'
action.save()

Meter an Action

Returns distance and duration traveled for the action, since the action was assigned to the user.

HTTP Request

GET https://api.hypertrack.com/api/v1/actions/<id>/meter/

Returns

Returns an object with distance and duration fields, if the call succeeded.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/meter/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.meter()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.meter(action, null);
action = HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.meter()

List all Actions

List all actions objects. The list can be filtered using the following parameters.

HTTP Request

GET https://api.hypertrack.com/api/v1/actions/

Returns

Returns a list of actions.

Parameters

Parameter Required Description
page_size No Maximum number of objects to return, default is 50
user_id No Filter actions that are assigned to a user
lookup_id No Filter actions by lookup id
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/?page_size=20
actions = hypertrack.Action.list()
HyperTrack::Action.list

Delete an Action

Delete an existing action object.

HTTP Request

DELETE https://api.hypertrack.com/api/v1/actions/<id>/

Returns

Empty response if the object is deleted.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/actions/f3ead2ae-dc0a-4a7e-85be-74ee51d9d70a/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.delete()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.delete(action);

results matching ""

    No results matching ""