Transfer a Prospect

When a prospect exists within a club chain, they are linked to their original club. This documentation explains the prospect migration process, which enables controlled prospect mobility within a club chain.

Retrouvez ce scénario dans notre collection Bruno

Gagnez du temps dans votre implémentation en observant l'enchaînement des appels et en récupérant les requêtes directement depuis Bruno.

Migration principle

Since a prospect record belongs to club A, if that same prospect wants to move to club B, they must start a migration process. From the prospect's perspective, this process consists of:

• Starting a migration request
• Receiving a confirmation code by SMS
• Entering the confirmation code

Warning

The network headers to use for each call may vary. The rule is to use the network headers of the location where the contact currently belongs.

• [Source club] Identify the contact you want to migrate
• [Source club] Initialize the migration
• [Source club] Validate the migration
• [Destination club] Only after validation can you use the destination club network headers

Start the migration

Prospect migration requires sending an SMS to the contact that contains a code to be used in the next step.

Example

curl --request POST \
  --url https://gateway.prod.gravitee.stadline.tech/{{env}}/{{clientToken}}/contact_migration_requests \
  --header 'Authorization: Bearer {{jwtToken}}' \
  --header 'X-Gravitee-Api-Key: {{apiKey}}' \
  --header 'content-type: application/json' \
  --header 'x-user-club-id: {{clubOneId}}' \ -- Source club
  --header 'x-user-network-node-id: {{clubOneNetworkNodeId}}' \ -- Source club
  --data '{
  "contactId":"{{contactId}}", -- Contact identifier
  "clubId":"{{clubTwoId}}" -- Destination club
}'

Response 201 Created

{  
   "@context":"\/clientToken\/contexts\/SignatureRequest",
  v------ Migration request identifier ------v
   "@id":"\/clientToken\/signature_requests\/455434",
   "@type":"SignatureRequest",
  // ...
}

Complete the migration process

Once the SMS is received, the application orchestrating the migration must collect the code from the targeted contact and complete the signature process by validating that code.

POST /{clientToken}/signature_requests/{signatureRequestId}/transitions

parameter	description	example
signatureRequestId	Identifier of the signature process previously created	3451
transition	Requested transition type. Possible values are validate or cancel	validate
code	Validation code received by SMS	1234

Example

curl --request POST \
  --url https://gateway.prod.gravitee.stadline.tech/{{env}}/{{clientToken}}/signature_requests/{{id}}/transitions \
  --header 'Authorization: Bearer {{jwtToken}}' \
  --header 'X-Gravitee-Api-Key: {{apiKey}}' \
  --header 'content-type: application/json' \
  --header 'x-user-club-id: {{clubOneId}}' \ -- Source club
  --header 'x-user-network-node-id: {{clubOneNetworkNodeId}}' \ -- Source club
  --data '{
    "transition": "validate",
    "code": "949875" -- The code received by SMS
}'

Response 201 Created

{
  "@context": "/demoapi/contexts/SignatureRequest",
  "@id": "/demoapi/signature_requests/23716",
  "@type": "SignatureRequest",
  "state": "validated",
  // ...
  "targetIds": [
    "/demoapi/clubs/1357"
  ],
  v------ Identifier of the contact created in the destination club ------v
  "resultTargetId": "/demoapi/contacts/2973829"
}

Referenced errors

400 : Bad Request Resource \"/{clientToken}/contacts/{id}\" does not exist.

This is related to the data sharing rules configured between clubs in a chain. You are currently operating for a club that does not have sufficient rights to access the contact record to migrate.

Solution: If you are authenticated with client_credentials and specify node headers, operate from a level above the club node.

400 : Bad Request api.error.contact.migration.club-not-valid

The target club is not valid. This happens when requesting a migration to the contact's current club.

Solution: Review the target club.

400 : Bad Request api.error.contact.migration.contact-not-valid

The contact cannot be transferred. This happens if the contact status is neither prospect nor former customer.

Solution: Review the contact.