Cookie Sync API – Send External IDs to Retargetly (/sync)

The /sync endpoint allows partners to send their own external user IDs to Retargetly so we can store the match in our identity graph.

This API supports two methods to pass Retargetly’s cookie ID:

Query string: Send userid as a query parameter. In this case, the _rlid cookie is not required.
Header: Send the _rlid cookie in the request header. In this case, the userid query parameter is not required.

When to Use This

Use this API if your platform wants Retargetly to store the mapping between your external ID and our internal _rlid.

Prerequisite: Retargetly’s Loop tag must already be implemented on your site or app.

API Endpoints

Use the appropriate endpoint based on the user's geographic region:

Region	Endpoint
America	`https://api.retargetly.com/sync`
Europe	`https://api-eu.retargetly.com/sync`

Query Parameters

Name	Description	Type	Required
`pid`	Platform ID. Provided by Retargetly.	Integer	Yes
`sid`	External User ID (e.g., from your platform).	String	Yes
`fp`	First-party cookie (UUID v4).	String	No
`userid`	Retargetly’s user ID (UUID v4).	String	Required only if `_rlid` cookie is not present
`gdpr_consent`	TCF v2.2 raw consent string.	String	Yes

Cookies

Name	Domain	Description	Type	Required
`_rlid`	`.retargetly.com`	Retargetly user ID (UUID v4).	String	Required only if `userid` query param is not provided

Usage Examples

1. Using `userid` as Query Parameter

https://api-eu.retargetly.com/sync?sid=9ba1b59e-2c0d-448b-ad3f-644d1f438428&pid=83&userid=58837c4b-c705-4836-beeb-25faae2554a1

2. Using `_rlid` Cookie Instead

curl --location 'https://api-eu.retargetly.com/sync?sid=9ba1b59e-2c0d-448b-ad3f-644d1f438428&pid=83'  --header 'Cookie: _rlid=58837c4b-c705-4836-beeb-25faae2554a1;'

Implementation Notes

You must send either userid (query param) or _rlid (cookie), but not both.
pid is your platform identifier. Contact your Retargetly team if you don't have it yet.
Use the API endpoint corresponding to the region of the user to comply with privacy regulations.

Region Mapping

America: Argentina, Bolivia, Brazil, Canada, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, Guatemala, Honduras, Mexico, Nicaragua, Panama, Peru, Puerto Rico, Paraguay, El Salvador, USA, Uruguay, Venezuela.

Europe: Austria, Belgium, Czech Republic, Denmark, Finland, France, Germany, Hungary, Ireland, Italy, Luxembourg, Netherlands, Norway, Poland, Romania, Spain, Sweden, Switzerland, United Kingdom, Albania, Andorra, Armenia, Belarus, Bosnia and Herzegovina, Bulgaria, Croatia, Estonia, Georgia, Greece, Iceland, Kosovo, Latvia, Liechtenstein, Lithuania, Malta, Moldova, Monaco, Montenegro, North Macedonia, Portugal, Russia, San Marino, Serbia, Slovakia, Slovenia, Ukraine.

🔁 Related

👉 If your platform will store the match instead, learn here how to use /getuid to retrieve Retargetly’s user ID (_rlid) via redirect.

Match External IDs with Loop's User IDs using a Tag

Cookie Sync – Retrieve Retargetly User ID (/getuid)