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. You never create consent requests directly. We create them for you when a requested operation requires user consent.

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 and the affected resource moves to the failed status. The affected resource also moves to failed if the consent request is canceled. You can retry the failed operation by recreating the affected resource, which creates a new consent request.

The notification for a consent request cannot be resent. If the user missed it, cancel or delete the affected resource, then recreate it to create a new consent request.

3. Wait for Completion

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

Consent Request Lifecycle

Consent Request Events

We notify you about consent requests via the following events: