Loop API
Loop is a tool that allows customers to submit missing events for review as well as provide feedback on existing events.
There are 2 main entry-points to the Loop system:
Loop UI - available at https://loop.predicthq.com and requires a PredictHQ user account.
Loop Links - low-code option to make the Loop functionality available to your end customers.
At this time the Loop Links functionality is available as an API (with other Loop functionality to follow in the future). Please see the Loop Integration Guide as well as the API reference docs below to get started.
Loop Links
Loop Settings
Submitted Events
Event Feedback
Search Loop Links
Retrieve list of Loop Links.
Query Parameters
Parameter | Description |
---|---|
q string |
Full-text search. E.g. ?q=hotel+a |
link_id string |
Comma-separated list of link_id .E.g. ?link_id=m4Dk4g4DRA8Yqbp2PC54 |
user_id string |
Comma-separated list of user_id .E.g. ?user_id=hw8Dsmv4Djg |
sort string |
Comma-separated list of sort options. Prefix the field name with - for reverse order.Possible values:
E.g. ?sort=name |
limit number |
The maximum number of results to return. The default limit is 10 .E.g. ?limit=10 |
offset number |
The number of results to skip. The default is 0 .E.g. ?offset=20 |
Action
GET /v1/loop/links
Response
{
"count": 1,
"next": null,
"previous": null,
"links": [
{
"link_id": "kt9fJZXpWFXSAdky9Bunb2",
"expire_dt": "2025-03-12T21:07:26.704000+00:00",
"name": "Hotel A",
"status": "active",
"create_dt": "2023-03-12T21:12:51+00:00",
"update_dt": "2023-03-12T21:12:51+00:00",
"metadata": {
"hotel_id": 123456789
},
"links": {
"event": "https://loop.phq.link/event/kt9fJZXpWFXSAdky9Bunb2",
"event_feedback": "https://loop.phq.link/event-feedback/kt9fJZXpWFXSAdky9Bunb2"
}
}
]
}
Create Loop Link
Create a new Loop Link.
Body Parameters
Parameter | Description |
---|---|
name string |
Name of the Loop Link. This is for your own use as a way to differentiate your Loop Links. E.g. Hotel ABC |
expire_dt datetime (or omitted) |
Date/time the Loop Link is set to expire in ISO 8601 format. All dates are in UTC. This is an optional field - omit if not needed. E.g. 2023-05-08T00:29:45.859Z |
metadata object (or omitted) |
Metadata can be used to further identify Loop Links in a way that makes sense for your system. The field is a key/value field that accepts string-based keys and string or numeric values. This can be useful for storing additional data such as a end-user identifier or store ID etc. This is an optional field - omit if not needed. E.g. { "hotel_id": "123456789" } |
Action
POST /v1/loop/links
Response
{
"link_id": "ber7ntO0ZHuFVCfrSNsN",
"create_dt": "2021-11-01T11:12:34",
"update_dt": "2021-11-01T11:12:34",
"expire_dt": "2021-11-01T11:12:34",
"name": "Hotel A",
"links": {
"event": "https://loop.phq.link/event/ber7ntO0ZHuFVCfrSNsN",
"event_feedback": "https://loop.phq.link/event-feedback/ber7ntO0ZHuFVCfrSNsN"
},
"metadata": {
"hotel_id": "123456789"
},
"status": "active"
}
Get Loop Link
Retrieve Loop Link by ID.
Response Fields
Field | Description |
---|---|
link_id string |
Loop Link Identifier. E.g. ber7ntO0ZHuFVCfrSNsN |
create_dt datetime |
Date/time the Loop Link was created in ISO 8601 format. All dates are in UTC. E.g. 2023-05-08T00:29:45.859Z |
update_dt datetime |
Date/time the Loop Link was last updated in ISO 8601 format. All dates are in UTC. E.g. 2023-05-08T00:29:45.859Z |
expire_dt datetime (or omitted) |
Date/time the Loop Link is set to expire in ISO 8601 format. All dates are in UTC. E.g. 2023-05-08T00:29:45.859Z |
user_id string (or omitted) |
The User ID of the user who created the Loop Link (if applicable). E.g. DiwBN4A0ZHuF |
name string |
Name of the Loop Link. This is for your own use as a way to differentiate your Loop Links. E.g. Hotel ABC |
links object |
These are the links your end-users need to open to access the Loop UI for submitting missing events or feedback about existing events. The different link types are: - event : This URL will present a page for submitting missing events.- event_feedback : This URL will present a page for providing feedback about an existing event.When using the event link you can optionally provide the following query string parameters:- email : Email address of the end-user who is providing the feedback. This will be stored against the submission so the user can receive email notifications about their submission.When using the event_feedback link you can optionally provide the following query string parameters:- event_id : Event ID to provide the feedback for (if this is not provided, the user will be asked to enter an Event ID).- email : Email address of the end-user who is providing the feedback. This will be stored against the submission so the user can receive email notifications about their submission. |
metadata object (or omitted) |
Metadata can be used to further identify Loop Links in a way that makes sense for your system. The field is a key/value field that accepts string-based keys and string or numeric values. This can be useful for storing additional data such as a end-user identifier or store ID etc. |
status string |
Status of the loop link. Possible values: - active |
Action
GET /v1/loop/links/<link_id>
Response
{
"link_id": "ber7ntO0ZHuFVCfrSNsN",
"create_dt": "2021-11-01T11:12:34",
"update_dt": "2021-11-01T11:12:34",
"expire_dt": "2021-11-01T11:12:34",
"name": "Hotel A",
"links": {
"event": "https://loop.phq.link/event/ber7ntO0ZHuFVCfrSNsN",
"event_feedback": "https://loop.phq.link/event-feedback/ber7ntO0ZHuFVCfrSNsN"
},
"metadata": {
"hotel_id": "123456789"
},
"status": "active"
}
Replace (Update) Loop Link
Replace Loop Link.
Body Parameters
Parameter | Description |
---|---|
name string |
Name of the Loop Link. This is for your own use as a way to differentiate your Loop Links. E.g. Hotel ABC |
expire_dt datetime (or omitted) |
Date/time the Loop Link is set to expire in ISO 8601 format. All dates are in UTC. This is an optional field - omit if not needed. E.g. 2023-05-08T00:29:45.859Z |
metadata object (or omitted) |
Metadata can be used to further identify Loop Links in a way that makes sense for your system. The field is a key/value field that accepts string-based keys and string or numeric values. This can be useful for storing additional data such as a end-user identifier or store ID etc. This is an optional field - omit if not needed. E.g. { "hotel_id": "123456789" } |
Delete Loop Link
Delete specified Loop Link.
Get Settings
These settings are used to control how certain elements might be displayed inside the Loop UI. Particularly for the Loop Links UI we take the org_name
from Settings and display it at the top of the page.
Response Fields
Field | Description |
---|---|
org_name string |
Name to display at the top of the Loop UI for end-users. This defaults to your Org name as per your PredictHQ account, however you can customize it here to make it different. E.g. My Org Name |
Replace (Update) Settings
Body Parameters
Parameter | Description |
---|---|
org_name string |
Name to display at the top of the Loop UI for end-users. This defaults to your Org name as per your PredictHQ account, however you can customize it here to make it different. E.g. My Org Name |
Search Submitted Events
Retrieve a list of events submitted by your organization. For example, you can use this to display a list of events submitted via Loop Links within your application to your users. See also the Events API documentation for more detail on many of the parameters mentioned below.
Query Parameters
Parameter | Description |
---|---|
q string |
Full-text search of event information. E.g. ?q=hotel+a |
link_id string |
Comma-separated list of link ids. Allows you to filter on events submitted via a specific Loop Link link id. E.g. ?link_id=m4Dk4g4DRA8Yqbp2PC54 |
event_id string |
Comma-separated list of event ids. Allows you to retrieve specific events. E.g. ?event_id=5uRg7CqGu7DTtu4Rfk |
user_id string |
Comma-separated list of user ids that submitted events. E.g. ?user_id=hw8Dsmv4Djg |
state string |
Comma separated list of event states. Possible values: active , predicted , cancelled , postponed , archived |
category string |
Comma separated list of event categories. E.g. ?category=expos,festivals |
label string |
Comma separated list of event labels. E.g. ?label=community,food,music |
country string |
Comma separated list of country codes. E.g. ?country=NZ,US |
start string |
The date from and/or to the event starts. Must be used with suffixes lt , lte , gt or gte .E.g. ?start.gt=2023-03-04&start.lte=2023-05-01 |
end string |
The date from and/or to the event ends. Must be used with suffixes lt , lte , gt or gte E.g. ?end.gt=2023-03-04&end.lte=2023-05-01 |
active string |
The date from and/or to the event is active. Must be used with suffixes lt , lte , gt or gte .E.g. ?active.gt=2023-03-04&active.lte=2023-05-01 |
created string |
The date from and/or to the event has been created. Must be used with suffixes lt , lte , gt or gte .E.g. ?created.gt=2023-03-04&created.lte=2023-05-01 |
updated string |
The date from and/or to the event has been updated. Must be used with suffixes lt , lte , gt or gte .E.g. ?updated.gt=2023-03-04&updated.lte=2023-05-01 |
private.include string |
Whether or not to include private events. Rejected & pending submitted events will always be private. Possible values: true , false , only .E.g ?private.include=only
|
org_review string |
Filter for submitted events approved, rejected or yet to be treated by the related org. Possible values: pending , approved , rejected .E.g ?org_review=approved |
phq_review string |
Filter for submitted events approved, rejected or yet to be treated by PHQ. Possible values: pending , approved , rejected .E.g ?phq_review=approved |
sort string |
Comma-separated list of sort options. Prefix the field name with - for reverse order.Possible values:
E.g. ?sort=-updated Defaults to ?sort=relevance,-updated |
limit number |
The maximum number of results to return. The default limit is 10 .E.g. ?limit=10 |
offset number |
The number of results to skip. The default is 0 .E.g. ?offset=20 |
Action
GET /v1/loop/events
Response
{
"count": 1,
"events": [
{
"event_id": "tae8Mie8keiceicoMae2ie",
"event": {
"title": "Hotel A event",
"description": "The 2023 edition of Hotel A festival.",
"category": "festivals",
"state": "active",
"metadata": [
{
"maximum_attendance": 5000
},
{
"attendance": 3215
}
],
"dates": {
"fixed_date": {
"start_date": "2023-06-02",
"end_date": "2023-06-04"
}
},
"labels": [
"festival",
"food",
"music"
],
"lat": "38.901544",
"lon": "-119.7030036",
"address": "859 U.S. Highway 395 North",
"formatted_address": "859 U.S. Highway 395 North\nGardnerville, Nevada 89410\nUnited States of America",
"city": "Gardnerville",
"region": "Nevada",
"postcode": "89410",
"country": "US",
"geometry": {
"type": "Point",
"coordinates": [
-119.703022,
38.9012446
]
}
},
"create_dt": "2023-02-16T00:52:11.112355+00:00",
"update_dt": "2023-05-09T02:05:51.695054Z",
"version": 1,
"phq_review": "approved",
"org_review": "pending",
"phq_auto_approved": false,
"link_id": "ber7ntO0ZHuFVCfrSNsN"
}
]
}
Search Submitted Feedback Conversations
Retrieve a list of event feedback conversations submitted by your organization. Conversations are used to track feedback on existing events for example feedback on incorrect attendance or start and end dates for an event. Each piece of feedback submitted by a user is tracked as a conversation and will be returned by this endpoint. You can use this to display a list of event feedback conversations submitted with Loop Links by users in your application.
Query Parameters
Parameter | Description |
---|---|
q string |
Full-text search over conversations. E.g. ?q=event+a+cancelled |
link_id string |
Comma separated list of loop link ids through which conversations were created. E.g ?link_id=m4Dk4g4DRA8Yqbp2PC54 |
conversation_id string |
Comma separated list of conversation ids. E.g ?conversation_id=Eeh4ahnohghah0deeshahda |
record_id string |
Comma separated list of event ids for which to fetch the related feedbacks. E.g ?record_id=5uRg7CqGu7DTtu4Rfk |
record_type string |
Comma separated list of record types for which to filter for. Possible values: event-individual , event-aggregate , event-public , event-loop , loop-backend .Use loop-backend for loop links feedback conversations.E.g ?record_type=loop-backend |
feedback_type string |
Comma separated list of feedback types. Possible values: attendance_or_rank , category , dates , general , polygon , venue E.g ?feedback_type=general |
user_id string |
Comma separated list of user ids that submitted those conversations. E.g ?user_id=hw8Dsmv4Djg |
status string |
Comma separated list of feedback status. Possible values: open , closed E.g ?status=open |
created string |
The date from and/or to the feedback has been created. Must be used with suffixes lt , lte , gt or gte .E.g. ?created.gt=2023-03-04&created.lte=2023-05-01 |
updated string |
The date from and/or to the feedback has been updated. Must be used with suffixes lt , lte , gt or gte .E.g. ?updated.gt=2023-03-04&updated.lte=2023-05-01 |
sort string |
Comma-separated list of sort options. Prefix the field name with - for reverse order.Possible values:
E.g. ?sort=-updated Defaults to ?sort=relevance,created |
limit number |
The maximum number of results to return. The default limit is 10 .E.g. ?limit=10 |
offset number |
The number of results to skip. The default is 0 .E.g. ?offset=20 |
Action
GET /v1/loop/feedback/conversations
Response
{
"count": 1,
"conversations": [
{
"record_id": "5uRg7CqGu7DTtu4Rfk",
"record_type": "loop-backend",
"status": "open",
"feedback": {
"type": "submitted"
},
"log": [
{
"action": {
"type": "created"
},
"timestamp": "2023-05-30T02:44:46+00:00",
"creator": {
"type": "unauthenticated_user",
"link_id": "m4Dk4g4DRA8Yqbp2PC54"
},
"note": "This event title should be different"
},
{
"action": {
"type": "comment"
},
"timestamp": "2023-05-30T02:59:11+00:00",
"creator": {
"type": "user",
"user_id": "hw8Dsmv4Djg"
},
"note": "Thank you for your feedback. Someone from PredictHQ will pick this up."
},
{
"action": {
"type": "comment"
},
"timestamp": "2023-05-30T03:41:06+00:00",
"creator": {
"type": "moderator"
},
"note": "Absolutely, we'll change this right away "
}
],
"create_dt": "2021-05-25T05:33:53+00:00",
"update_dt": "2021-05-25T05:38:08+00:00",
"link_id": "m4Dk4g4DRA8Yqbp2PC54",
"conversation_id": "Eeh4ahnohghah0deeshahda"
}
]
}