EventsObjectives

Objectives

Retrieve a Single Event Objective by ID #

Method
GET
Endpoint
Sample Object

Retrieves a single Event Objective by its ID.

Parameters
Name Type Required? Description Details
id Number Yes
The ID of the Event Objective.
$result_format String No
By default, the response is a single object. Send array to get it inside a one-item array.
Allowed values: array | object
$include_record_revision Boolean No
Whether to include a record_revision for a later update.
Default: false. Set true to include the token described below.
$on_error_return_empty_result Boolean No
Whether an invalid or unavailable Objective should return an empty result.
Default: false. True returns HTTP 200 with {} (or [] for array format) for invalid IDs or an unavailable Objective. Authentication failures, records that change while they are read and unexpected errors keep their normal status.
If-None-Match String No
An ETag from an earlier response to this GET.
Optional HTTP header. If the successful response is unchanged, the API returns HTTP 304 with no body.

What $include_record_revision covers

Setting $include_record_revision=true returns record_revision for use as expected_revision on a later update.

The token covers this Objective's type, name, importance, achievement rating and current Event. Read it again if an update reports that the Objective changed.

Access

Your workspace plan must include ROI, and you need read access to the Event's ROI / ROO area. The tab can be locked while you read it.

Code Samples
curl -X GET "https://api.exhibitday.com/v1/events/objectives/info?id=12345" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": 12345,
  "event_id": 23456,
  "event_name": "Illustrative Event",
  "objective_type_id": 1,
  "objective_type": "Lead Generation",
  "name": "Lead Generation",
  "importance_id": 2,
  "importance": "Medium",
  "achievement_rating": 8,
  "objective_created_timestamp": "2030-01-03T14:30:00Z"
}
Note: IDs are illustrative; use IDs from your workspace.

Retrieve Event Objectives #

Method
GET
Endpoint

Retrieves Event Objectives across the Events you can read.

Parameters
Name Type Required? Description Details
filter_by_event_id Number No
Only include Objectives from this Event.
Omit to search readable Events across your workspace.
$limit Number No
The most Objectives to return.
A positive whole number. Omit for all remaining Objectives.
$offset Number No
The number of Objectives to skip.
A whole number of 0 or more. Default: 0.
$result_format String No
By default, the response is an object containing list_data and the paging totals (records_found, total_records, has_more). Send array to get just a JSON array of the records, or wrapped_in_array to get the default object inside a one-item array.
Allowed values: array | wrapped_in_array
If-None-Match String No
An ETag from an earlier response to this GET.
Optional HTTP header. If the successful response is unchanged, the API returns HTTP 304 with no body.

Good to know

Retrieves objectives across readable Events. Use filter_by_event_id to retrieve the objectives for one Event.

Filtering and paging

Omit filter_by_event_id for all readable Events in your workspace. The current plan, Budget View permission and each Event's ROI visibility apply before counts and paging.

A supplied Event that is missing or unavailable returns an empty list with a warning. A readable Event with no objectives returns an empty list without that warning.

Results are ordered by added timestamp, then objective ID. Omit $limit for all remaining matching objectives; $offset defaults to 0. Each objective retains its actual event_id and Event name.

Events with a hidden ROI tab

Records on Events whose ROI tab is hidden are not listed. If filter_by_event_id names such an Event, the response is HTTP 200 with no records for it and a warning that names the tab and the Event.

Code Samples
curl -X GET "https://api.exhibitday.com/v1/events/objectives" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "list_type": "objective",
  "list_data": [
    {
      "id": 12345,
      "event_id": 23456,
      "event_name": "Illustrative Event",
      "objective_type_id": 1,
      "objective_type": "Lead Generation",
      "name": "Lead Generation",
      "importance_id": 2,
      "importance": "Medium",
      "achievement_rating": 8,
      "objective_created_timestamp": "2030-01-03T14:30:00Z"
    },
    {
      "id": 12346,
      "event_id": 23456,
      "event_name": "Illustrative Event",
      "objective_type_id": 11,
      "objective_type": "Other",
      "name": "Meet potential partners",
      "importance_id": 3,
      "importance": "High",
      "achievement_rating": null,
      "objective_created_timestamp": "2030-01-03T14:30:00Z"
    }
  ],
  "records_found": 2,
  "total_records": 2,
  "has_more": false
}
Note: IDs are illustrative; use IDs from your workspace.

Add an Event Objective #

Method
POST
Endpoint

Adds an Objective to an Event.

Parameters
Name Type Required? Description Details
event_id Number Yes
The ID of the Event.
objective_type_id Number Yes
The type of Objective to add.
Use an ID from Objective Types. For Other (11), also supply name.
name String When objective_type_id is 11 (Other)
The name of an Other Objective.
Up to 75 characters, excluding surrounding spaces. Must not be blank for Other. Ignored for other types. For a name containing commas, use JSON, a form field or a query parameter.
importance_id Number No
How important this Objective is. Omit or send null for Medium. Choose an importance currently available in the workspace.
Allowed values: 1 (Low) | 2 (Medium) | 3 (High)
achievement_rating Number No
How well this Objective was achieved.
A whole number from 0 through 10. Omit or send null for Not Rated Yet.
$result_format String No
By default, the response is a single object. Send array to get it inside a one-item array.
Allowed values: array | object
Idempotency-Key String No
A unique key for safely retrying this add request.
Optional HTTP header: 1 to 255 visible ASCII characters without spaces. Retry with the same key and identical request to replay its first saved response. Use a new key for a different request.

Good to know

Use the Objective to track importance and rate achievement.

Choosing an Objective

Choose a type from GET /v1/references/objective_types. It lists the built-in types and your workspace's named custom Objectives.

Each type can be added once per Event, except Other (11), which permits several differently named Objectives. Other names are compared without regard to case. A duplicate returns HTTP 400.

The type and name are fixed when the Objective is added. To change either later, delete that Objective and add another one.

After the add

A successful request returns the new Objective, including its id, and adds one entry to Event history. It sends no notification.

If the save outcome cannot be confirmed, retrieve the Event's Objectives before deciding whether to retry.

Access

Your workspace plan must include ROI. The Event's ROI / ROO area must be available and unlocked, and you need permission to edit it.

Hidden or locked tab

If the Event's ROI tab is hidden or locked, this request returns HTTP 400 (not_allowed), and the message names the tab. Show or unlock the tab in ExhibitDay first. An Event that is not in your workspace returns HTTP 404.

Code Samples
curl -X POST "https://api.exhibitday.com/v1/events/objectives" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"event_id\":23456,\"objective_type_id\":1,\"importance_id\":2}"

Example response

{
  "id": 12345,
  "event_id": 23456,
  "event_name": "Illustrative Event",
  "objective_type_id": 1,
  "objective_type": "Lead Generation",
  "name": "Lead Generation",
  "importance_id": 2,
  "importance": "Medium",
  "achievement_rating": null,
  "objective_created_timestamp": "2030-01-03T14:30:00Z"
}
Note: IDs are illustrative; use IDs from your workspace.

Update an Event Objective #

Method
PATCH
Endpoint

Updates an existing Event Objective.

Parameters
Name Type Required? Description Details
id Number Yes
The ID of the Event Objective.
importance_id Number No
How important this Objective is. Omit or leave blank to keep it; null cannot clear it. Choose an importance currently available in the workspace.
Allowed values: 1 (Low) | 2 (Medium) | 3 (High)
achievement_rating Number No
How well this Objective was achieved.
A whole number from 0 through 10. Omitted or blank values leave the rating unchanged. Null resets it to Not Rated Yet.
expected_revision String No
The record_revision from a previous read of this Objective.
Optional. Obtain it from GET /v1/events/objectives/info with $include_record_revision=true. A changed Objective returns HTTP 409 without saving this update.
$ignore_params_with_empty_values Boolean No
Whether to leave a JSON null achievement_rating unchanged.
Default: false. With true, JSON null is ignored. The text null still resets the rating to Not Rated Yet. Blank values already leave fields unchanged.

Choosing what to change

Send importance_id, achievement_rating, or both. Omit a value to keep it. To remove the rating, send achievement_rating=null.

A change adds one entry to Event history. An unchanged request saves no data or history and keeps the same revision. It sends no notification.

Using expected_revision

  1. Retrieve this Objective with GET /v1/events/objectives/info and $include_record_revision=true.
  2. Send its unchanged record_revision value as expected_revision with this update.
  3. If the API returns HTTP 409 because the Objective changed, read the current Objective and decide what to update.

Access and an unconfirmed save

Your workspace plan must include ROI. The Event's ROI / ROO area must be available and unlocked, and you need permission to edit it.

If the save outcome cannot be confirmed, read the Objective before deciding whether to retry.

Hidden or locked tab

If the Event's ROI tab is hidden or locked, this request returns HTTP 400 (not_allowed), and the message names the tab. Show or unlock the tab in ExhibitDay first. An Event that is not in your workspace returns HTTP 404.

Code Samples
curl -X PATCH "https://api.exhibitday.com/v1/events/objectives" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"id\":12345,\"achievement_rating\":8}"

Example response

{
  "status_code": 200,
  "status": "OK",
  "message": "Objective updated.",
  "errors": []
}

Delete an Event Objective #

Method
DELETE
Endpoint

Deletes an existing Event Objective.

Note: Inputs that do not apply to this operation, including the ignore-empty option, are ignored and reported in the X-API-Warnings response header.

Parameters
Name Type Required? Description Details
id Number Yes
The ID of the Event Objective.

After the deletion

The Objective is removed from the Event's ROI / ROO area and the deletion is recorded once in Event history. It sends no notification.

Deleting an Objective that is no longer available returns HTTP 404. If the save outcome cannot be confirmed, retrieve the current Objectives before deciding whether to retry.

Access

Your workspace plan must include ROI. The Event's ROI / ROO area must be available and unlocked, and you need permission to delete its content.

Hidden or locked tab

If the Event's ROI tab is hidden or locked, this request returns HTTP 400 (not_allowed), and the message names the tab. Show or unlock the tab in ExhibitDay first. An Event that is not in your workspace returns HTTP 404.

Code Samples
curl -X DELETE "https://api.exhibitday.com/v1/events/objectives?id=12345" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "status_code": 200,
  "status": "OK",
  "message": "Objective removed.",
  "errors": []
}