Creating or Updating a Single Profile
One by one calls should be preferred when the data are used to trigger a workflow or that they must be immediately synchronized with a database.
Moreover, they allow you to focus specific elements of the profile table, such as subscriptions or segmentations.
Creating or updating a single profile
It is possible to create or to update one profile through the operation POST/entity{e}/table{t}/profile
This method involves using a JSON code block in order to submit the data associated to the given profile. It is therefore advised to get to know the structure of the database beforehand, as explained in the 'Obtaining the structure of a profile table' point of the main profile APIs page.
The following parameters must be provided:
-
The entity to which the table belongs:
-
The name of the profile table to which the profile will be added, or the containing the profile to be updated
-
"allowupdate": This parameter allows you to choose whether you want to update a profile should it exist already. Indeed, POST is above all a creation method, but it can be used for updates
-
The characteristics of the given profile, inserted as JSON code. The schema to the right of the Swagger technical documentation provides you with a model of the expected structure of this code. It is made of 4 sections:
-
"attributes"
The expected value is an array containing all the information belonging to the profile to be created. Each element is made of the name of the attribute and the associated value.
Each 'mandatory' attribute (as defined in the table structure) must necessarily have a value, while this is not the case for optional attribute. In the latter case, you can either not mention it at all in your call, or post it with a "null" value. Technical attributes should not be mentioned in your call. In fact, they cannot be modified and they will be automatically generated during the creation.
-
"dataCollectionInformation"
These parameters did not appear in the structure of a profile as you may have obtained it through a GET method. As a matter of fact, it consists in information related to GDPR that will be stored in your back office in order to be able to justify the marketing consent given by a profile. It relates to: the information collection moment ("date"), its origine ("source") and the technical information related to the means of collection ("way").
-
"subscriptions"
The set of subscriptions appear in the "subscription" array. You should indicate the name of the subscription then specify whether the profile subscribed to it (true) or not (false) in the "subscribe" parameter. Subscriptions that do not appear in the entry will not ta taken into account.
-
"segmentations"
The set of segmentations appear in the "segmentation" array. You should indicate the name of the segmentation then, in the "category" parameter, specify the name of the segment if it is an exclusive segmentation, or "Member" if it is a simple segmentation.
Example of request including JSON code posted in the "profile" parameter : (Download this example)
Curl call:curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"attributes\": [{
\"name\": \"lastName\",
\"value\": \"Wayne\"
}, { \"name\": \"firstName\",
\"value\": \"John\"
}, { \"name\": \"birthDate\",
\"value\": \"26/05/1907\"
}, { \"name\": \"sex\",
\"value\": \"M\"
}, { \"name\": \"motherLanguage\",
\"value\": \"EN\"
}, { \"name\": \"emailAddress\",
\"value\": \"john.wayne@actito.com\"
}, { \"name\": \"addressLocality\",
\"value\": \"Los Angeles\"
}, { \"name\": \"addressCountry\",
\"value\": \"US\"
}, { \"name\": \"gsmNumber\",
\"value\": \"1223344556\"
}, { \"name\": \"customerId\",
\"value\": 34567
}, { \"name\": \"nbChildren\",
\"value\": 2
}, { \"name\": \"rep\",
\"value\": \"null\"
} ], \"dataCollectionInformation\": {
\"date\": \"15/03/2019\",
\"source\": \"TEST\",
\"way\": \"api profile 1\"
}, \"subscriptions\": [{
\"name\": \"Newsletter\",
\"subscribe\": \"true\"
}, { \"name\": \"Offer\",
\"subscribe\": \"true\"
} ], \"segmentations\": [{
\"belongs\": \"true\",
\"segmentation\": {
\"name\": \"TypeClient\",
\"category\": \"Gold\"
} }, { \"belongs\": \"true\",
\"segmentation\": {
\"name\": \"Active\",
\"category\": \"Member\"
} } ]}" https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/Demodoc/profile?allowUpdate=true
Response body:
{ "profileId": 1147690
}The response will be the technical id auto-generated by ACTITO at each creation of a new profile (profileId). If you use this operation to update an existing profile, it will be the id the updating profile.
Behavior in case of multiple unique keys in the database
When this operation is used for updating a profile and that the "allowUpdate" has been therefore set as true, the link with the existing profile will be based on a key attribute. If the JSON object contains more than one key (for instance, a profile id and a unique e-mail address), the following rules will be applied to find the matching profile:
-
For each value of unique attribute found in the file, the program will search for the matching profile
-
If all the non-unique field values match the same profile, the profile is updated
-
If two or more field values match different profiles, a conflict is generated and the update is not applied
-
If no matching profile can be found, the system will create a new one
Updating a single profile
To update an existing profile, it is possible to use the previous operation by setting the "allowUpdate" parameter as true.
If you want to update a profile without any possibility to create a new profile if it does not exist (therefore avoiding any risk of duplicate in case of mistake with the id), you can the operation PUT/entity/{e}/table{t}/profile{p}
In such a case, the JSON body can only contain information that shall be updated. Unaffected elements should not be mentioned in the request at all. For example, if you want to update some attributes, without modifying subscriptions and segmentations, the "subscriptions" and "segmentations" sections shall be left empty or not mentioned at all.
Example of request: (Download this example)
Curl call:curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"attributes\": [{
\"name\": \"addressLocality\",
\"value\": \"Hollywood\"
}, { \"name\": \"rep\",
\"value\": \"1\"
} ]}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/profile/1147690"
Response body:
{ "profileId": 1147690
}Subscribing or unsubscribing a profile
To modify the subscriptions preferences of a profile, it is possible to use the two operations explained above. In this case, you need to modify the "subscribe" parameter of each subscription, depending on whether the profile has subscribed to it (true) or not (false).
However, there are operations at your disposal to focus specifically on subscribing or unsubscribing a profile.
It is possible to subscribe a profile to a subscription through the operation POST/entity/{e}/table{t}/profile/{p}/subscription/{s}
It is possible to unsubscribe a profile from a subscription through the operation DELETE/entity/{e}/table{t}/profile/{p}/subscription/{s}
In both cases, the parameters you need to fill in are exactly the same:
-
The entity to which the profile table belongs
-
The profile table in which the profile appears
-
The profile whose subscription will be modified ("profileId" or pair "keyAttribute=Value")
-
The name of the subscription that shall be added to or remove from the profile. It is the display name that you selected at creation, not its technical id
-
Data collection information ("source", "way" and "date"). This information is not mandatory but it is a good practice regarding the GDPR.
Tip
These operations do not provide any response body.
Adding or removing a profile from a segmentation
To modify the segmentations to which belongs a profile, it is possible to use both main creation and update operations explained above.
In this case, you will have to modify the "belongs" parameter of each segmentation, depending on whether the profile must belong to it (true) or not (false).
For exclusive segmentations, which are made of segments sub-categories, it is possible that a profile shall not be remove from the segmentation, but only transferred into another segment. You will therefore have to modify the "category" parameter with the name of the segment to which the profile now belongs. As a matter of fact, in the case of an exclusive segmentation with mandatory partition (meaning that each profile must obligatorily belong to a segment), it will not be possible to remove a profile from the segmentation but only to change the segment to which it belongs.
However, there are operations existing specifically to add, update and delete the affiliation of a profile with a segment.
Adding or updating the segmentation of a profile
The operation PUT/entity{e}/table{t}/profile{p}/segmentation{s} allows you to add a profile to a segmentation or, in the case of an exclusive segmentation, to modify the segment to which it belongs.
The parameters you need to fill in are:
-
The entity to which the profile table belongs
-
The profile table in which the profile appears
-
The profile whose segmentation will be modified ("profileId"or pair "keyAttribute=Value")
-
The name of the segmentation. The expected value for this parameter depends on whether it is a simple or an exclusive segmentation:
-
simple segmentation
The expected value is the name of the segmentation
-
exclusive segmentation
The expected value should be formatted as 'segmentName;category=categoryName', where 'segmentName' is the name of the general segmentation and where 'categoryName' refer to its sub-categories of segments.
For example, in the case of an exclusive segmentation 'clientType' including the 'Gold', 'Silver' and 'Bronze' segments: To put a profile in the 'Gold' segment, the parameter will be 'clientType;category=Gold'.
Tip
This operation does not provide any response body.
Removing a profile from a segmentation
The operation DELETE/entity{e}/table{t}/profile{p}/segmentation{s} allows you to remove a profile from a segmentation.
-
The entity to which the profile table belongs
-
The profile table in which the profile appears
-
The profile whose segmentation will be modified ("profileId" or "keyAttribute=Value" pair)
-
The name of the segmentation.
In this case, no difference is made between simple and exclusive segmentations. The profile is simply removed from the segmentation.
It is not possible to remove the profile from a segment in order to put it in another segment. For this purpose, you need to use the PUT method explained previously.
In the case of a mandatory exclusive segmentation (meaning that each profile must obligatorily belong to a segment), it will not be possible to remove a profile from the segmentation but only to change the segment to which it belongs. Attempting to remove a profile from a mandatory exclusive segmentation will yield a 401 error.
Tip
This operation does not provide any response body.
Deleting a profile
It is possible to delete a profile through the ACTITO APIs. However, please note that such a deletion has consequences. We therefore invite you to read the 'Deleting a profile' page beforehand to assess the impact of this action.
You can delete a profile through the operation DELETE/entity{e}/table{t}/profile{p}
The parameters of this operation are simply the entity of the profile table, the profile table and the id of the profile to be deleted ("profileId" or pair "keyAttribute=Value")
Tip
Success will be indicated by a 200 response code.
The ACTITO APIs can only delete profiles one by one. Mass deletion of profiles is only possible through the ACTITO interface. To learn how to do so, we invite you to read the 'Deleting profiles based on a list' page.