# Onboarding

This section outlines the process for onboarding new entities (Parents or Merchants) using the Partner APIs. The API schemas for both are similar, with a few key parameters that define the new entity.

The primary fields to consider when onboarding are the entity's name, its position in the hierarchy, and the security credentials returned in the response.

* `entityName`: This is a simple, required string that defines the name of the new entity being onboarded (e.g., `parentName` or `merchantName`).
* `grandparentId` or `parentId`: This parameter is crucial for establishing the hierarchy. It's the unique identifier (ID) of the entity under which the new entity will be onboarded.
  * If not specified while onboarding a parent as a grandparent or merchant as a parent, this value will default to the grandparentId or parentId of the auth token you are using.
* `theme`: This optional object allows for the customization of the UPP Optty portal's appearance for the new entity. It provides granular control over the UI, including:
  * `logo`: A string representing the URL for the entity's logo.
  * Color Fields: Strings for background, active, hover, and text colors for both the left sidebar and top bar, allowing for brand alignment.
  * `paymentLinkMenuAlias`: A string to customize the name of the payment link (optty direct) menu item.
* `popupOverlayConfig`
  * The title and message displayed on your page when the inContext checkout flow is in progress (either in an iframe or seperate popup)

{% hint style="info" %}
If you are completely replicating the portal functionality via API, the `theme` object will have no effect on this process and can be passed as an empty object (`{}`).
{% endhint %}

The fields returned are

* `parentId` or `merchantId`: This parameter is crucial for establishing the hierarchy. It's the unique identifier (ID) of the entity under which the new entity will be onboarded.
* `authSecret`: This is a crucial security credential. Along with the entity's ID, it is used to generate an access token for making API calls as that specific entity.
* `hmacKey`: This security-related field is only relevant for Merchants. It is used for signature validation when checking the return signature.

{% hint style="info" %}
The parentId and merchantId also act as the respective clientId when generating an auth token for the newly onboarded entity
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.optty.com/partner-onboarding-docs/onboarding-api/onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.