Quick start

This guide walks you through your first call to the CRM API. You will exchange your credentials for an OAuth 2.0 token, create a guest with the Create a guest endpoint, and read the new profile back.

No credentials yet? Import the API collections and run any request against the mock environment straight away, with no credentials. Add your OAuth 2.0 credentials when you are ready to call the live API.

Prerequisites

Get the following from D-EDGE before starting:

Token endpoint: the URL of the D-EDGE CRM ID server that issues your tokens.
OAuth 2.0 credentials: client ID and client secret.
API base URL: the base URL for your environment.
Entity identifier: the entity whose guest profiles you manage, a UUID.

All are delivered during the build step of your integration journey, after the partnership agreement.

Install an OAuth 2.0 library

The token exchange is a plain form POST, so any HTTP client can do it. A library is still worth it: it caches the token and renews it when it expires, which matters here because tokens live 300 seconds. Skip this step if you only use cURL.

npm install simple-oauth2

pip install requests-oauthlib

composer require league/oauth2-client

dotnet add package IdentityModel

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>oauth2-oidc-sdk</artifactId>
    <version>11.10.1</version>
</dependency>

Make your first call

Get a token, then send a POST to the Create a guest endpoint. Each attribute pairs a value with a from field naming who provided the information, and emails takes an object rather than a plain string. The full field list is documented in the Reference.

# 1. exchange your credentials for a token
curl --request POST \
  --url https://{tokenUrl} \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

# 2. create a guest with the access_token from the response
curl --request POST \
  --url https://{apiBaseUrl}/api/guestprofile/entities/{entityId}/guests/create \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstname": {"value": "Martin", "from": "guest"},
    "lastname": {"value": "Dupont", "from": "guest"},
    "emails": [{"value": {"email": "martin.dupont@example.com"}, "from": "guest"}]
  }'

import { ClientCredentials } from "simple-oauth2";

const tokenUrl = new URL("https://{tokenUrl}");

const client = new ClientCredentials({
  client: {
    id: process.env.DEDGE_CLIENT_ID,
    secret: process.env.DEDGE_CLIENT_SECRET,
  },
  auth: { tokenHost: tokenUrl.origin, tokenPath: tokenUrl.pathname },
  options: { authorizationMethod: "body" },
});

const token = await client.getToken({});
const entityId = process.env.DEDGE_ENTITY_ID;

const response = await fetch(
  `https://{apiBaseUrl}/api/guestprofile/entities/${entityId}/guests/create`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token.token.access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      firstname: { value: "Martin", from: "guest" },
      lastname: { value: "Dupont", from: "guest" },
      emails: [{ value: { email: "martin.dupont@example.com" }, from: "guest" }],
    }),
  }
);

console.log(response.status, response.headers.get("location"));

import os
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

client = BackendApplicationClient(client_id=os.environ["DEDGE_CLIENT_ID"])
session = OAuth2Session(client=client)
session.fetch_token(
    token_url="https://{tokenUrl}",
    client_id=os.environ["DEDGE_CLIENT_ID"],
    client_secret=os.environ["DEDGE_CLIENT_SECRET"],
)

entity_id = os.environ["DEDGE_ENTITY_ID"]

response = session.post(
    "https://{apiBaseUrl}/api/guestprofile/entities/" + entity_id + "/guests/create",
    json={
        "firstname": {"value": "Martin", "from": "guest"},
        "lastname": {"value": "Dupont", "from": "guest"},
        "emails": [{"value": {"email": "martin.dupont@example.com"}, "from": "guest"}],
    },
)

print(response.status_code)
print(response.headers.get("location"))

require 'vendor/autoload.php';

use League\OAuth2\Client\Provider\GenericProvider;
use GuzzleHttp\Client;

$provider = new GenericProvider([
    'clientId'                => getenv('DEDGE_CLIENT_ID'),
    'clientSecret'            => getenv('DEDGE_CLIENT_SECRET'),
    'urlAccessToken'          => 'https://{tokenUrl}',
    'urlAuthorize'            => '',
    'urlResourceOwnerDetails' => '',
]);

$token = $provider->getAccessToken('client_credentials');
$entityId = getenv('DEDGE_ENTITY_ID');

$client = new Client(['base_uri' => 'https://{apiBaseUrl}/']);

$response = $client->post("api/guestprofile/entities/$entityId/guests/create", [
    'headers' => ['Authorization' => 'Bearer ' . $token->getToken()],
    'json'    => [
        'firstname' => ['value' => 'Martin', 'from' => 'guest'],
        'lastname'  => ['value' => 'Dupont', 'from' => 'guest'],
        'emails'    => [['value' => ['email' => 'martin.dupont@example.com'], 'from' => 'guest']],
    ],
]);

echo $response->getStatusCode() . "\n";
echo $response->getHeaderLine('location');

using System.Net.Http.Json;
using IdentityModel.Client;

var http = new HttpClient();

var token = await http.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
    Address = "https://{tokenUrl}",
    ClientId = Environment.GetEnvironmentVariable("DEDGE_CLIENT_ID"),
    ClientSecret = Environment.GetEnvironmentVariable("DEDGE_CLIENT_SECRET"),
    ClientCredentialStyle = ClientCredentialStyle.PostBody
});

var entityId = Environment.GetEnvironmentVariable("DEDGE_ENTITY_ID");

var client = new HttpClient { BaseAddress = new Uri("https://{apiBaseUrl}") };
client.SetBearerToken(token.AccessToken);

var response = await client.PostAsJsonAsync(
    $"/api/guestprofile/entities/{entityId}/guests/create", new
{
    firstname = new { value = "Martin", from = "guest" },
    lastname = new { value = "Dupont", from = "guest" },
    emails = new[] { new { value = new { email = "martin.dupont@example.com" }, from = "guest" } }
});

Console.WriteLine(response.StatusCode);
Console.WriteLine(response.Headers.Location);

import com.nimbusds.oauth2.sdk.*;
import com.nimbusds.oauth2.sdk.auth.*;
import com.nimbusds.oauth2.sdk.id.ClientID;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

ClientAuthentication auth = new ClientSecretPost(
    new ClientID(System.getenv("DEDGE_CLIENT_ID")),
    new Secret(System.getenv("DEDGE_CLIENT_SECRET"))
);

TokenRequest tokenRequest = new TokenRequest(
    URI.create("https://{tokenUrl}"), auth, new ClientCredentialsGrant());
String accessToken = TokenResponse.parse(tokenRequest.toHTTPRequest().send())
    .toSuccessResponse().getTokens().getAccessToken().getValue();

String entityId = System.getenv("DEDGE_ENTITY_ID");
String body = """
    {
      "firstname": {"value": "Martin", "from": "guest"},
      "lastname": {"value": "Dupont", "from": "guest"},
      "emails": [{"value": {"email": "martin.dupont@example.com"}, "from": "guest"}]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://{apiBaseUrl}/api/guestprofile/entities/" + entityId + "/guests/create"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.headers().firstValue("location").orElse(""));

Inspect the response

A successful creation returns 200 OK with an empty body and a location header holding the path of the new profile. The last path segment is the guest identifier, which is what you store on your side.

location: /api/guestprofile/entities/{entityId}/guests/55468764-64be-4fc1-a43f-e37239e012bf

Read the profile back with the Get a guest endpoint. Each attribute comes with the source that provided it and the date it last changed, and the CRM fills in what it can infer:

{
  "id": "55468764-64be-4fc1-a43f-e37239e012bf",
  "entityId": "{entityId}",
  "type": "guest",
  "createdAt": "2026-08-14T09:24:11.000000Z",
  "firstname": {
    "from": "guest",
    "value": "Martin",
    "updated": "2026-08-14T09:24:11Z"
  },
  "lastname": {
    "from": "guest",
    "value": "Dupont",
    "updated": "2026-08-14T09:24:11Z"
  },
  "emails": [
    {
      "from": "guest",
      "value": {"email": "martin.dupont@example.com"},
      "updated": "2026-08-14T09:24:11Z",
      "preferred": true
    }
  ],
  "gender": {
    "from": "system",
    "value": "M",
    "updated": "2026-08-14T09:24:11Z"
  }
}

See the response schema for the full structure.

Common issues

Status	Likely cause	Where to look
`401`	The bearer token is missing, invalid, expired, or does not give access to the entity	Authentication
`400`	Validation error: malformed body or invalid property	Responses
`500`	An attribute sent in the wrong shape, such as an email as a plain string instead of an object	Requests

Next steps

Reference

Endpoint specifications, parameters, and response schemas.

Guidelines

Authentication, request conventions, and response formats.

Best practices

Patterns for clean profiles, from sourcing to deduplication.

Get started

Build

Resources

Prerequisites

Install an OAuth 2.0 library

Make your first call

Inspect the response

Common issues

Next steps

Reference

Guidelines

Best practices

​Prerequisites

Install an OAuth 2.0 library

Make your first call

Inspect the response

​Common issues

​Next steps

Reference

Guidelines

Best practices

Prerequisites

Common issues

Next steps