# 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. Do you order a low volume of checks? Do you expect little to no in-progress checks in legacy during migration? → Consider our [immediate cutover](#a-immediate-cutover) migration pathway.
2. Do you order a high volume of checks? Do you expect many in-progress checks during migration? → 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

**Migration transition period: Short (<1 day)**

For clients that can afford to suspend having in-flight checks during the migration window (typically low volume clients), we recommend immediately cutting over to Centric during migration to simplify the process. This involves:

1. Taking note of how many in-progress checks you expect to normally have during the migration window. If you are comfortable with the number of in-progress checks you'll need to hold off on during this time, proceed to the next step. Otherwise, consider a [phased rollout](#b-phased-rollout-with-parallel-operations).
2. [Requesting a **migration date** here](https://forms.gle/CHLBVXaVxDPzZWCt6). Please await a confirmation response from Certn that we can handle this date. Migration dates must be requested **at least 10 business days** beforehand.
3. Certn will set up a production Centric account within 5 business days after requesting an expected migration date. Ensure you can log in and generate a production API key that will be used by your new API integration after migration.
4. Prepare to pause ordering of background checks 1 week or more before the date of migration to ensure all checks have completed before migration begins. This can be done via code in your legacy API integration or by revoking your API token/key in your legacy Certn client portal.
5. Notify Certn if there are any in-progress checks the day before expected migration so the migration can be pushed out. Monitor and reengage with Certn when all in-progress checks are completed.
   1. *Note: In the event you wish to proceed while checks are in progress, you will need to support receiving webhooks from both legacy and Centric systems simultaneously in order to see when the case is complete. You must also request a follow-up point-in-time sync of cases from legacy to Centric once all in-progress cases have been completed.*
6. On the agreed-upon day and time of migration, Certn will take a point-in-time snapshot of your data in the legacy Certn portal. This data will be copied over to your new Centric account. **Certn will also disable your legacy client portal at this time.** [See what is migrated over here.](#what-gets-migrated-what-doesnt)
7. Certn will contact you once the migration has completed. After you have done initial smoke testing and verification that the production Centric instance is set up appropriately, you are free to enable the Centric API integration in your production environment, reenabling ordering of checks in the process.

#### B. Phased Rollout with Parallel Operations

**Migration transition period: Short-Medium (>1 day to 30 days)**

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 decide on one of a variety of phased rollout approaches such as net-new groups & users accessing CertnCentric first followed by existing groups or users as they become eligible for data migration (which happens when they have no in progress cases in legacy). Alternatively you may consider only using Centric exclusively for brand new case orders across all groups 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-upon day and time of migration, Certn will take a point-in-time snapshot of your data in the legacy Certn portal. This data will be copied over to your new Centric account. [See what is migrated over here.](#what-gets-migrated-what-doesnt)
   1. Important Note! Checks can be in progress during the migration - but they won't be included in the initial migration and can only be brought into Centric at a later time once complete.
5. Certn will contact you once the migration has completed. You will have 30 days from migration to finish your transition to Centric. After this point, the legacy Certn platform will automatically be disabled.
6. Any in-progress checks in legacy Certn that complete after migration will be automatically migrated over to Centric on a nightly basis.
7. Once all your in-flight cases have completed in legacy Certn, you can request one final data migration and let Certn know to disable Legacy.

### 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 |  |
| 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 | ⛔ No - can only be migrated over once complete |
| 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 implements data domiciling - clients that operate in north america, europe, and/or asia-pacific regions will need to set up settings/groups/API keys for each region (CA = North America; UK = Europe, Middle East, Africa; AU = Asia Pacific). Base URLs for API endpoints differ across these data regions. Please consult the Centric API portal for more information about this.
* SSO must be reconfigured and tested separately.

### Managing In-Progress Cases in Legacy

If you choose to temporarily operate in both systems:

* Existing in-flight cases remain in Legacy.
* New cases can begin in Centric.
* In-progress Legacy cases cannot be manually moved to Centric. They must either complete or be cancelled in Legacy before being migrated to Centric.
* Certn runs a nightly script that checks a migrated client's legacy instance for any newly-closed checks since the time of migration. Any newly-closed checks are automatically migrated over to Centric when this script runs.

### 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?
- [ ] (For "Immediate Cutover" clients only) Have you, or are you planning on instituting a freeze on any new background orders at least 10 business days prior to the migration date (which will serve as the cutover date)?
- [ ] 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 phase approach, the *"after migration"* phase is time bound to a maximum of 30 days. During this time, verify and confirm the Centric production environment, its settings, and its data are working as expected.

- [ ] 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.
- [ ] (For "Phased Rollout" clients only) Verify with Certn that Legacy access can be turned off once all legacy in-flight cases (applications) are complete.

### FAQ

**Can Legacy and Centric run simultaneously?**
Yes. They are standalone systems with their own users, groups, settings, and cases. They do not communicate with one another.

**How long can I run Legacy and Centric simultaneously?**
For those who have chosen the phase rollout approach, both systems will be functional during an overlapping time. Once migration has occurred to Centric, you have **30 days** before the legacy Certn platform is disabled.

**Will there be downtime with my migration to Centric?**
No. Migration does not require downtime unless a customer chooses an immediate (e.g. coordinated) cutover, which would necessitate a partial downtime as it requires pausing ordering of Certn checks before migration can occur. See "[Immediate Cutover](#a-immediate-cutover)".

**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)".

**Can in-progress (in-flight) Legacy cases be manually moved to Centric?**
No. Cases can only be migrated to Centric once they are completed.

**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*