Operations with User Consent

To prevent fraud and protect privacy, we treat certain operations as sensitive and require explicit user approval before executing them. These operations require user consent only if this feature is enabled in the project settings.

User consent is modeled in the Gigs API as a consent request. Consent requests are created automatically when an operation requires user consent. The only ones you create yourself are retries: if the user misses the code or link, you can create a new consent request from the existing one.

Examples of operations requiring user consent are:

• Creating a port out
• Requesting a SIM exchange by creating a subscription change
• Porting a phone number into a subscription in Ireland

Process

1. Request an Operation that Requires Consent

You request the operation via the API as usual, for example by creating a port out. If the operation requires user consent, the affected resource is created in the initiated status and we automatically create a consent request for it.

You receive a com.gigs.consentRequest.created event containing the new consent request. The consent request's operation indicates which operation requires approval, for example issue.portOutCredentials, and its subject contains the ID of the affected resource, for example the port out. You can retrieve the consent request at any time to check its status.

2. User Approval

The user is asked to approve the operation via the consent request's deliveryMethod:

• Email link (emailLink): The user receives an email with a link to an approval page hosted by Gigs, where they review and approve the operation.
• SMS link (smsLink): The user receives an SMS with a link to the same approval page.
• SMS OTP (smsOTP): The user receives an SMS with a one-time password. The user provides the code to you, and you approve the consent request on their behalf:

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/consentRequests/${CONSENT_REQUEST_ID}/approve" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "code": "123456"
  }'

Reach out to your account manager if you are interested in other delivery options.

Once the user approves, you receive a com.gigs.consentRequest.approved event, the operation proceeds, and the affected resource moves to the next status in its lifecycle, for example processing for a port out.

If the user doesn't approve in time, the consent request expires: after 5 hours when delivered via email, or after 15 minutes when delivered via SMS. You receive a com.gigs.consentRequest.expired event. An expired consent request stays expired, but it doesn't fail the affected resource: the resource keeps waiting for consent, and you can create a new consent request from the expired one to deliver a fresh link or code to the user.

For consent requests delivered via SMS OTP, the user has 5 attempts to enter the correct code. After the fifth incorrect code, the consent request expires and the affected resource moves to failed immediately.

3. Wait for Completion

Our system now processes the requested operation. You can monitor its progress by tracking the status of the affected resource.

Retrying a Consent Request

If the user missed the notification or the code expired, you can retry by creating a new consent request from the existing one. The new consent request covers the same operation and resource, and the user receives a newly generated link or code:

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/consentRequests" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "fromConsentRequest": "'"${CONSENT_REQUEST_ID}"'"
  }'

The referenced consent request must be pending or expired, and it must be the most recent one for its resource. A pending one expires as soon as the new one is created, so only one consent request is open for a resource at a time. If a newer consent request already exists, the request fails with the consentRequestSuperseded error code, and the error names the current one. A consent request whose code attempts ran out cannot be recreated, because the affected resource has already failed.

Every attempt keeps its own record: retrying doesn't modify or delete earlier consent requests.

Finding the Current Consent Request

A resource can go through several consent requests, so the one you saw created first isn't necessarily the current one. List the consent requests for a resource to find it. Consent requests are sorted by creation date, with the most recent one first:

curl --request GET \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/consentRequests?subject=${RESOURCE_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

You can also filter by subscription and status.

When the Affected Resource Fails

Retries don't extend the overall deadline. The affected resource moves to the failed status when:

• No consent request is approved within 48 hours of the first one being created for the resource. The deadline is set by the first consent request and doesn't move when a new one is created.
• The user enters 5 incorrect codes on a consent request delivered via SMS OTP. This expires the consent request and fails the resource immediately.
• The consent request is canceled.

Once the resource has failed, you can retry the operation by recreating the affected resource, which starts over with a new consent request.

Consent Request Lifecycle

Consent Request Events

We notify you about consent requests via the following events: