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.

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:
  • created
  • updated
  • expires
  • name

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

raw
GET /v1/loop/links

Response

json
{
    "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

raw
POST /v1/loop/links

Response

json
{
  "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

raw
GET /v1/loop/links/<link_id>

Response

json
{
  "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" }

Action

raw
PUT /v1/loop/links/<link_id>

Response

raw
204 No Content

Delete Loop Link

Delete specified Loop Link.

Action

raw
DELETE /v1/loop/links/<link_id>

Response

raw
204 No Content

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

Action

raw
GET /v1/loop/settings

Response

json
{
  "org_name": "My Org"
}

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

Action

raw
PUT /v1/loop/settings

Response

raw
204 No Content

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
  • true: private and public events
  • false (default): only public events
  • only: only private events
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:
  • created
  • updated
  • version
  • relevance

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

raw
GET /v1/loop/events

Response

json
{
    "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:
  • created
  • updated
  • relevance

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

raw
GET /v1/loop/feedback/conversations

Response

json
{
    "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"
        }
    ]
}