On this page

Some requests are held until the customer proves the email address they gave, for example a request submitted through a form under an address that has not been confirmed yet. DevStride normally emails them a confirmation link. In headless mode it sends you a request_confirmation message instead, and your tool does the confirming.

  1. A customer.message arrives with kind request_confirmation. Keep data.message.verificationToken.
  2. Ask the customer to confirm their address in your own tool, in whatever way you trust.
  3. Once they have, call POST /service-desk/requesters/confirm with the token.

This does exactly what the customer clicking DevStride's own link would: the request is released into your queue, the requester becomes active, and every other request of theirs still held is released with it. The address is proven, not just the one request.

Needs: Manage Requesters.

Request#

Field Required Meaning
token Yes The verificationToken from the request_confirmation message, exactly as received (up to 512 characters).
curl -X POST "https://api.devstride.com/v1/organizations/$ORG_ID/service-desk/requesters/confirm" \
  -u "$DEVSTRIDE_API_KEY:$DEVSTRIDE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "token": "EXAMPLE-TOKEN-not-a-real-value" }'

Response#

{
  "confirmed": true,
  "requesterId": "1c6e8a4b-3d9f-4b2e-8a7c-5f0d2b9e6a41",
  "itemNumber": "I4823"
}
Field Meaning
confirmed true when the token was accepted.
requesterId The requester the token belongs to.
itemNumber The request the token was issued for.

What to know#

  • It is safe to repeat. Confirming the same token again returns the same answer and changes nothing.
  • It never reinstates a blocked or erased requester. The request is released, but a requester your team blocked stays blocked.
  • The token works only in the organization that issued it.

Refusals#

Status When
400 The token is missing, malformed, or was not issued by this organization. The message gives no further detail, on purpose.
401 / 403 The key is missing or invalid, or its owner lacks Manage Requesters.

Confirming a changed contact address#

When staff change a contact's email address, the new address has to prove it works, and the contact shows Unverified until it does. DevStride normally emails the new address a confirmation link. In headless mode it sends you a contact_email_confirmation message instead, and your tool does the confirming. Staff can also resend the confirmation from the contact; each resend is a new message with a new token.

  1. A customer.message arrives with kind contact_email_confirmation. Keep data.message.confirmationToken.
  2. Ask the customer to confirm the address in your own tool, in whatever way you trust.
  3. Once they have, call POST /service-desk/requesters/email-confirmation/{token} with the token in the path.

This does exactly what the customer clicking DevStride's own link would: Unverified clears and the address counts as proven. If the contact had requests held for confirmation, they are released too.

Needs: nothing beyond the token. The token is the proof, so the call takes no API key. This is the same call DevStride's own confirmation page makes.

curl -X POST "https://api.devstride.com/v1/organizations/$ORG_ID/service-desk/requesters/email-confirmation/$TOKEN"
{ "confirmed": true }
  • The token works once. A second call with the same token answers confirmed: false.
  • Only the newest token works. A resend, or another change of address, replaces the earlier token.
  • It expires after 7 days. Ask staff to resend the confirmation after that.
  • Every failure reads the same: an unknown, used, expired or malformed token, or a blocked or erased contact, all answer { "confirmed": false } with no further detail, on purpose.
Powered by DevStride