# Certn API Documentation - Migrating Legacy Integrations

> Source: https://centric-api-docs.certn.co/#migrating-legacy-integrations
> Interactive docs: https://centric-api-docs.certn.co/#migrating-legacy-integrations

## Migrating Legacy Integrations

Information and recommendations for API customers transitioning from the Legacy platform to the Centric platform.

This guide provides information and recommendations on how API clients can prepare for a well-organized and coordinated migration of their API integration from legacy Certn to CertnCentric. Migration refers to the set of coordinated processes that must take place with you, the client, and Certn, to productionize your API integration in CertnCentric. Migration on Certn's end mainly comprises provisioning a CertnCentric account for you, and copying (not actually "moving") data from your Legacy Certn environment into the new CertnCentric environment.

At a high level, migration is not required to be a "lightswitch upgrade" - it is not required to move over to Centric all at once. Both the Legacy and CertnCentric systems remain operational, and live in isolation from one another. This means your Legacy and CertnCentric accounts can coexist alongside each other with their own settings, users, checks, and reports, etc. This will allow for migrations without (or at least minimized) disruptions and downtime, while also providing an avenue for rolling back for a contingency plan (in the rare case this is necessary).

Please read on to familiarize yourself with migration options and best practices so you know what to prepare for on your end when you request the migration.

### Migration Strategies

Since Legacy and CertnCentric are set up independently, there is flexibility in how you go about migrating, however, certain factors should be considered when determining how you wish to migrate. In general, clients that order a higher volume of checks (e.g. resellers) should adhere to a more rigorous, phased migration plan over clients with lower or spotty volumes of checks. Ask yourself:

1. Are you ready to send all new background check orders to Centric on your migration date? → Consider our [immediate cutover](#a-immediate-cutover) migration pathway.
2. Do you need to move users, groups, or new orders to Centric gradually? → Consider our [parallel operations](#b-phased-rollout-with-parallel-operations) migration pathway instead.

Migration strategy options do not account for time spent building, testing, or validating your new Centric API integration works. **Ensure you understand when you will be done with this work before settling on a migration strategy and request a migration date as described below.**

#### A. Immediate Cutover

**New ordering transition period: Short (<1 day)**

For clients that are ready to send all new background check orders to Centric on the migration date, an immediate cutover offers the simplest transition. This involves:

1. [Request a **migration date** here](https://forms.gle/CHLBVXaVxDPzZWCt6). Please await confirmation from Certn. Migration dates must be requested **at least 10 business days** beforehand.
2. Certn will set up a production Centric account within 5 business days after you request a migration date. Ensure you can log in and generate a production API key for your new API integration.
3. Confirm that all new background check orders will move to Centric on the agreed migration date. If you need a gradual transition, consider a [phased rollout](#b-phased-rollout-with-parallel-operations).
4. On the agreed day and time, Certn will copy your Legacy data, including in-progress cases, to your new Centric account. Cases already in progress will continue in Legacy without interruption. Their migrated Legacy case statuses in Centric will be updated as they change in Legacy until completion. [See what is migrated over here.](#what-gets-migrated-what-doesnt)
5. Certn will contact you once the migration is complete. After you have verified that your Centric account and API integration work as expected, you can begin sending all new orders to Centric.
6. Legacy access normally ends 7 days after migration. Contact Certn before migration if you need a longer transition period. Every migration requires an agreed date for Legacy access to end.

#### B. Phased Rollout with Parallel Operations

**New ordering transition period: 7 days by default; longer by request**

1. [Request a **migration date** here](https://forms.gle/CHLBVXaVxDPzZWCt6). Please await a confirmation response from Certn that we can handle this migration date. Migration dates must be requested **at least 10 business days** beforehand.
2. Certn will confirm your migration request and set up a production Centric account within 5 business days of your request. Ensure you can log in and generate a production API key that will be used by your new API integration.
3. Develop a change management strategy that outlines which groups, checks, or users will start using the new Centric API integration and when this will happen. You may begin with new groups and users before moving existing groups and users, or you may send only new case orders to Centric during the transition period.
   1. **Note** - You are free to start ordering from the Centric system via API as soon as it is available for net-new users and groups, however we do not recommend allowing orders from existing users and groups (i.e. "teams" in legacy) in Centric before Certn has run a data migration that brings them and their historical account activity into Centric.
4. On the agreed day and time, Certn will copy your Legacy data, including in-progress cases, to your new Centric account. Cases already in progress will continue in Legacy without interruption. Their migrated Legacy case statuses in Centric will be updated as they change in Legacy until completion. [See what is migrated over here.](#what-gets-migrated-what-doesnt)
5. Certn will contact you once the migration is complete. Legacy access normally ends 7 days after migration. Contact Certn before migration if you need a longer transition period. Every migration requires an agreed date for Legacy access to end.
6. If a Legacy case is missing from Centric, contact Certn to request a follow-up migration.

### What Gets Migrated? What Doesn't?

When Certn performs a data migration, only certain specific items are migrated from Legacy to Centric.

##### Superteam → Customer Account

| Legacy field | Centric field |
| :---- | :---- |
| superteam\_id | CustomerAccount.legacy\_id |
| superteam\_name | CustomerAccount.auth0\_display\_name |
| (constant) | CustomerAccount.source \= CASE\_MANAGEMENT\_CREATED |
| (constant) | CustomerAccount.legacy\_source \= CERTN |
| business\_number (primary team) | CustomerAccount.business\_number |
| account\_manager\_email | CustomerAccount.account\_manager (FK User) |
| buttercup/prepay subsidiary | CustomerAccount.subsidiary |
| primary team address | CustomerAccount.address |
| team\_phone | CustomerAccount.contact\_phone |
| team\_email | CustomerAccount.contact\_email |
| (on create) | MigrationProfile (centric\_status \= DATA\_MIGRATING) |

##### Team → Group

| Legacy field | Centric field |
| :---- | :---- |
| team\_id | CustomerGroup.legacy\_id |
| internal\_name / settings config | CustomerGroup.name |
| org\_name | CustomerGroup.applicant\_facing\_name |
| team\_type (HR/PM) | CustomerGroup.permissible\_purpose |
| team address | CustomerGroup.address |
| (link) | CustomerGroup.billing\_profile |

##### User (Active) → User

| Legacy field | Centric field |
| :---- | :---- |
| accounts\_user.email | User.email |
| first\_name \+ last\_name | User.full\_name |
| phone | User phone number |
| created | User.start\_date |
| permission\_level 0–3 | User.role (Client Portal Admin/Manager/Contributor/Billing) |
| (link) | User.client\_account → CustomerAccount |
| (link) | User.customer\_groups (M2M) |

##### Service Collection → Package

| Legacy field | Centric field |
| :---- | :---- |
| servicecollection\_id | – (no Package.legacy\_id) |
| package/posting name | Package.name |
| package owner email | Package.created\_by (User FK) |
| request\_\* boolean flags | PackageCheck.check\_type \+ PackageCheck.arguments |
| team/package settings | CheckArgumentsTemplate (employment, ICRC, CV) |
| (link) | Package.customer\_account |

##### Apply Link → Apply Link

| Legacy field | Centric field |
| :---- | :---- |
| building name or posting position\_name | ApplyLink.name |
| building\_apply\_link or posting url\_code | ApplyLink.url\_code |
| owner / requestor email | ApplyLink.requestor (User FK) |
| (link) | Package.default\_apply\_link |

##### Property Buildings / Listing Names → Tags

| Legacy field | Centric field |
| :---- | :---- |
| applications\_property.building | Tag.name (lowercased) |
| applications\_listing.name | Tag.name (lowercased) |
| (link) | CustomerAccount |

##### Application → Legacy Case (historical, not live Case)

| Legacy field | Centric field |
| :---- | :---- |
| applications\_applicant\_id | LegacyCase.legacy\_applicant\_id |
| short\_uid | LegacyCase.report\_id |
| superteam\_id | LegacyCase.customer\_account (via legacy\_id) |
| team\_id | LegacyCase.customer\_group (via legacy\_id) |
| information\_first\_name | LegacyCase.applicant\_first\_name |
| information\_last\_name | LegacyCase.applicant\_last\_name |
| account\_applicant\_email | LegacyCase.applicant\_email |
| order/report status | LegacyCase.status, report\_status |
| result / overall\_score | LegacyCase.score |
| request\_\* flags | LegacyCase.checks (array) |
| adjudication\_status | LegacyCase.adjudication\_status |
| co-signer info | LegacyCase.co\_signers (JSON) |
| listing unit/building | LegacyCase.listing\_data (JSON) |
| tag | LegacyCase.tag |
| application\_created\_date | LegacyCase.created |
| application\_requester\_email | LegacyCase.requested\_by (User FK) |
| PDF (async) | LegacyCase.pdf\_report\_s3\_key |
| consent docs (async) | LegacyCase.consent\_documents\_s3\_keys |
| CSV (async) | LegacyCase.csv\_report\_s3\_key |

##### Secondary items

| Data category | Maintains ID across systems? | Migrated? |
| :---- | :---- | :---- |
| Case reports & attachments | ⛔ No | ✅ Yes - as "archived cases" which cannot be modified |
| Pricing | N/A | ✅ Yes |
| Equifax Credit / Acic Credentials | N/A | ✅ Yes |
| Payment Profile | ⛔ No | ✅ Yes |
| Billing Profile | ⛔ No | ✅ Yes |
| Legacy Invoice | ⛔ No | ✅ Yes |
| Settings | N/A | ✅ Yes |
| Inactive users | N/A | ⛔ No |
| Case comments | N/A | ⛔ No |
| Cases older than 3 years | N/A | ⛔ No |
| Billing credits | N/A | ⛔ No |
| Custom questionnaire | N/A | ⛔ No |
| In-progress cases | N/A | ✅ Yes - migrated Legacy case statuses in Centric continue to update as the cases progress in Legacy |
| ATS integrations | N/A | ⛔ No |
| API tokens/keys | N/A | ⛔ No |
| Webhooks | N/A | ⛔ No |
| SSO configurations | N/A | ⛔ No |

### Technical Considerations

Legacy and Centric operate as **separate environments** with **separate production and sandbox URLs**.

It's important to know:

* No automatic URL redirects exist from Legacy to Centric → Users should update bookmarks and documentation.
* API integrations must be rebuilt to work in Centric. All API reference documentation can be found at [https://centric-api-docs.certn.co](https://centric-api-docs.certn.co)
* API keys must be reissued in Centric - legacy API keys cannot be used in Centric.
* Centric is available in several regions. United States and Canadian clients use the North American instance; clients in Europe, the Middle East, and Africa use the UK instance; and clients in Asia Pacific use the Australian instance. Each region has its own settings, groups, API keys, and API base URL. Please consult the Centric API portal for more information.
* SSO must be reconfigured and tested separately.

### Managing In-Progress Cases in Legacy

If you choose to temporarily operate in both systems:

* Cases already in progress continue in Legacy without interruption and are also available as archived cases in Centric.
* Their migrated Legacy case statuses in Centric are updated as the cases progress in Legacy until completion.
* New cases can begin in Centric.
* If a Legacy case is missing from Centric, contact Certn to request a follow-up migration.

### Legacy Access and Deactivation

Legacy access normally ends 7 days after migration. If you need more time, contact Certn before migration to agree on a longer transition period. Every migration requires an agreed date for Legacy access to end.

### Migration Readiness Checklist

Before calling your Centric migration complete, review the items in this checklist:

#### Before migration

- [ ] Do you have access to a CertnCentric Sandbox environment?
- [ ] Have you built, tested, and validated an API integration with CertnCentric on Sandbox?
- [ ] Has your integration gone through testing & validation that it works properly with Centric in Sandbox?
- [ ] Have you decided on a migration pathway? I.e. immediate cutover vs phased rollout?
- [ ] Have you begun executing on a change management plan for your users (or customers for resellers)? Have you highlighted any material changes to their experience in your system from Legacy to Centric?
- [ ] Take inventory of all items that you will need to reconfigure in Centric. Build in timelines to set these up in Centric:
  - [ ] API keys?
  - [ ] Webhook URLs?
  - [ ] ATS integrations?
  - [ ] SSO?
- [ ] Have you requested and received confirmation of a migration date with Certn? Does this date give you enough time to finish your integration, set up your production instance of CertnCentric beforehand?
- [ ] Have you confirmed the date when your Legacy access will end? If you need more than the standard 7 days after migration, have you requested an extension?
- [ ] Have you received access to your new CertnCentric Production account?
- [ ] Have you configured your production CertnCentric account with [items that won't migrate over](#secondary-items) like ATS integrations, API keys, Webhook URLs, and SSO configuration?

#### After migration

**Please note** — for clients doing a phased approach, the *"after migration"* phase is a transition window to verify Centric and complete your rollout before the agreed Legacy access end date.

- [ ] Run a smoke test of the API integration in the CertnCentric production environment.
- [ ] Confirm all expected **users** have migrated over to Centric with the correct permissions/role. Consider using the Legacy API and Centric API to pull this list from each system. This can be as thorough as you wish - ranging from a quick audit of a few users to a complete validation of every user. Reference legacy Users to Centric Users by email.
- [ ] Confirm all expected **teams** have migrated over to Centric as groups. Consider using the Legacy API and Centric API to pull this list from each system. This can be as thorough as you wish - ranging from a quick audit of a few groups to a complete validation of every group. Reference legacy Groups (Teams) to Centric Groups by group name.
- [ ] Confirm all expected **cases** were migrated over. Consider using the Legacy API and Centric API to pull this list from each system. Again, this can be as thorough as you wish - ranging from a quick audit of a few cases to a complete validation of every case. Reference legacy Case IDs to Centric Legacy Case IDs.
- [ ] Complete execution of your change management plan to have all users aware of and comfortable with the use of CertnCentric.
- [ ] Turn on access for users (or customers for resellers) to start using your new API integration with CertnCentric. For phased rollout customers, consider opening up access to users (or if you are a reseller, clients) in groups to build confidence in the newly-deployed integration. This also allows you to limit risks to small groups at a time.
- [ ] If an expected Legacy case is missing from Centric, contact Certn to request a follow-up migration.

### FAQ

**Can Legacy and Centric run simultaneously?**
Yes. You can continue using Legacy during the transition period while you begin using Centric.

**How long can I run Legacy and Centric simultaneously?**
Legacy access normally ends 7 days after migration. Contact Certn before migration if you need a longer transition period. Every migration requires an agreed date for Legacy access to end.

**Will there be downtime with my migration to Centric?**
No. Migration does not require downtime. Ensure your Centric API integration is tested and ready before you begin sending new orders to Centric.

**Are ATS integrations migrated?**
No. These will require re-configuring in Centric

**Is SSO migrated?**
No. It must be re-configured and tested in Centric.

**What will migrate over to Centric?**
See "[What Gets Migrated?](#what-gets-migrated-what-doesnt)".

**Will my legacy case/application/report IDs change?**
See "[What Gets Migrated?](#what-gets-migrated-what-doesnt)".

**Will user and group IDs remain the same?**
See "[What Gets Migrated?](#what-gets-migrated-what-doesnt)".

**Are in-progress (in-flight) Legacy cases migrated to Centric?**
Yes. The cases continue in Legacy without interruption and are also available as archived cases in Centric. Their migrated Legacy case statuses in Centric are updated as the cases progress in Legacy until completion.

**Will legacy URLs redirect to Centric?**
No. Ensure your change management plan has a strategy for communicating out the new Centric Client Portal URL.

**How do reports differ?**
Reports in Centric are generally more detailed and may be presented in a different format than in Legacy.

**How do I get support for an API issue?**
Please contact [apisupport@certn.co](mailto:apisupport@certn.co) with any questions you have.

---

## Additional Resources

- [Interactive Documentation](https://centric-api-docs.certn.co)
- [OpenAPI Specification](https://centric-api-docs.certn.co/openapi.yaml)
- [All Reference Docs](https://centric-api-docs.certn.co/reference/)

*Generated from Certn API Documentation*