Add Person to Flow

Use this API endpoint to add a Person to flow and create/update person within people module beforehand if needed.

Resource

https://api.infobip.com/communication/1/flows/:flowId/participants

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Content-Type: application/json

Parameters

This API endpoint uses path, query, and request body parameters. Query parameter and request body by itself are optional, however at least one of them needs to be provided.

Path parameters - Mandatory

  • flowId - unique identifier of the flow that person will be added to.

Query parameters - Optional

Unique identifier of a person that needs to be added to flow and updated or created if it does not exist, following identifiers are supported:

Property name Type Description Case-insensitive
phone number Person’s phone number no
email string Person’s email address yes
externalId string Unique ID for a person from an external system no
pushRegistrationId string Unique ID for push registration yes

Only one query parameter is allowed to be set.

Body parameters - Optional

Contains the data used for person creation (if it does not exist) or partial update (if it exists).

Body example

{
	"personData": {
		"externalId": "1",
		"firstName": "Jane",
		"lastName": "Smith",
		"address": "67 Farringdon Road",
		"city": "London",
		"country": "United Kingdom",
		"gender": "FEMALE",
		"birthDate": "1966-01-15",
		"middleName": "Janie",
		"profilePicture": "http://profile.com",
		"tags": [
			"VIP Customers",
			"New Customers"
		],
		"customAttributes": {
			"Contract Expiry": "2018-06-01",
			"Company": "Acme"
		},
		"contactInformation": {
			"phone": [{
					"number": "41793026727"
				},
				{
					"number": "41793026728"
				}
			],
			"email": [{
					"address": "jane@acme.com"
				},
				{
					"address": "janesmith@acme.com"
				}
			]
		}
	}
}	
  
  • Person data is provided within the personData field of outer request wrapper object.
    • Person data model (within personData field) is exactly the same as specified on People API and supports all fields specified there: https://dev.infobip.com/people/person-profile
    • In order to create a person contactInformation field with one valid contact is mandatory within personData as is on People API.
    • In case of updating the person only provided fields will be updated on the Person.

Basic usage examples

Creating a new Person and adding it to flow

When adding a new person to flow, only flowId and request body which will be used to create the Person has to be provided. If for example a duplicate person already exists by given contactInformation or externalId, an error will be thrown, you can find the full list of error codes under Response error codes.

Request example

POST https://api.infobip.com/communication/1/flows/10159347/participants
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"personData": {
		"lastName": "Williams",
		"address": "10 York Street",
		"contactInformation": {
			"email": [{
				"address": "janewilliams@gmail.com"
			}]
		}
	}
}	
  

Response example 200 OK

Body empty	
  

400 Bad Request

{
    "errorCode": 40002,
    "errorMessage": "Error creating person: Email address already exists"
}	
  

Upserting a person and adding it to flow

When upserting a person both query parameter and request body needs to be provided. If a Person with an identifier given through query parameter does not exist, it will be created. If a Person exists, it will be updated only with fields given in the request (rest of the fields on the person will not be altered). If the person is already in the flow, an error will be thrown.

Request example

POST http://P7-IO-AMG-2:8080/communication/1/flows/135395/participants?email=janewilliams@gmail.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"personData": {
		"lastName": "Williams",
		"address": "10 York Street",
		"contactInformation": {
			"phone": [{
				"number": "3859128592198"
			}]
		}
	}
}	
  

Response example

200 OK

Body empty	
  

400 Bad Request

{
    "errorCode": 40003,
    "errorMessage": "Error updating person: msisdn: Number is invalid."
}	
  

Adding an existing person to flow

When adding an existing person to flow, only flowId and person identifier query parameter have to be provided. If the person is already in the flow, an error will be thrown. If externalId of the person is used as an identifier, and a Person does not exist, an error will be thrown. As a special case when the request body is not provided and a Person does not exist for given query parameter identifier, query parameter will be used to create a new person containing only the contact given through it (only for provided phone/email as those are valid person destinations).

Request example

POST https://api.infobip.com/communication/1/flows/10159347/participants?email=janewilliams@gmail.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

Body empty	
  

Response example

200 OK

Body empty	
  

Response error codes

Error ErrorCode HTTP status
Bad request 40001 400
Duplicate person 40002 400
Person manipulation failed 40003 400
Person already in flow 40004 400
Flow inactive 40005 400
Flow not found 40401 404
Person not found 40402 404
Internal server error 50001  

Use case examples

Webshop welcome messages

Welcome messages are one use case for which Flow API will be used. Flow is created to send a welcome message to all newly registered users. In case of a webshop, it can be an email with current offers and a small discount that will encourage a user to do his first purchase. Once a user signs up to a webshop by entering his email and first name, the web site sends a request to Flow API URL provided in the launched Flow. Infobip receives the request and adds this user to the flow. The user then receives a welcome message.

Request and response examples

Request example - new user registration

POST https://api.infobip.com/communication/1/flows/10159347/participants
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"personData": {
		"firstName": "John",
		"contactInformation": {
			"email": [{
				"address": "johndoe@gmail.com"
			}]
		}
	}
}	
  

Response example - new user registration

200 OK

Body empty	
  

400 Bad Request

{
    "errorCode": 40002,
    "errorMessage": "Error creating person: Email address already exists"
}	
  

Satisfaction surveys

Satisfaction surveys are another use case for which Flow API will be used. Flow is created to ask customers how satisfied they are with the purchased product. Each time a product is delivered to a person, courier marks parcel as delivered which can be used as an event that triggers Flow API. Since satisfaction survey comes at the end of the customer journey, let’s say that user data already exists on the Infobip side (stored in People module which in this case poses as an address book). The most important information here is External ID which is a unique identifier of each person available on the delivery platform side. In that case, request to the Flow API URL doesn’t need to contain the recipient’s data. External ID is enough for Flow to know which person should receive messages. Once the Flow API receives External ID, it will do a lookup (in the People module) and include in Flow person with all information found.

Request and response examples

Request example - start survey flow for the user

POST https://api.infobip.com/communication/1/flows/10159347/participants?externalId=8edb24b5-0319-48cd-a1d9-1e8bc5d577ab
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

Body empty	
  

Response example - start survey flow for the user

200 OK

Body empty	
  

400 Bad request

{
    "errorCode": 40402,
    "errorMessage": "Person not found for given identifier, and not enough person data is provided for creation"
}