Add Person to Flow

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

• JSON

{
	"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

• HTTP

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

• JSON

Body empty	
  

400 Bad Request

• JSON

{
    "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

• HTTP

POST POST http://api.infobip.com/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

• JSON

Body empty	
  

400 Bad Request

• JSON

{
    "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

• HTTP

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

• JSON

Body empty	
  

Response error codes

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

• HTTP

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

• JSON

Body empty	
  

400 Bad Request

• JSON

{
    "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

• HTTP

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

• JSON

Body empty	
  

400 Bad request

• JSON

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