Frequently Asked Questions
Authentication
Why don't my appKey and appSecret credentials work?
appKey and appSecret credentials work?Those are credentials for a different (Salesforce Connected App) integration path. The CorpNet Business Formation and Tax Registration APIs use a single static Bearer token issued by CorpNet during partner onboarding. There is no token exchange or OAuth flow. If you were issued appKey + appSecret, contact your CorpNet account manager for the correct Bearer token. See Authorization.
Does the same key work for both APIs?
Yes, if your partner agreement covers both products. Partners who have licensed only one product receive a token entitled to that product only; calls to the other product return 403 Forbidden. Partners with both products receive a single token entitled to both.
How do I rotate a key?
Contact your CorpNet account manager. Old tokens stop working as soon as a replacement is issued — there is no overlap window. See API Key.
Business Formation gotchas
Where is the order GUID in the create-order response?
At data.partnerOrder.orderGuid. The response is a full echo of the submitted order, not a summary — parsers reading data.orderGuid will get null.
Why is my response body a string instead of JSON?
The API delivers responses as JSON-encoded strings that contain JSON. Clients must double-decode:
body = await resp.json(content_type=None)
if isinstance(body, str):
body = json.loads(body)Response Content-Type may also be text/plain rather than application/json. See the Business Formation API overview.
Why am I getting Please enter a value for ResponsiblePartySSN?
Please enter a value for ResponsiblePartySSN?You set responsibleParty.responsiblePartyStatus: "Yes", which cascades both responsiblePartySSN AND responsiblePartyEmail as required. Recommended pattern: send "No" from your integration and have your customer supply SSN through CorpNet's portal post-submission — collecting SSNs in a third-party UI is rarely worth the compliance burden.
Why am I getting Please enter a value for RegisteredAgentFirstName when isCorpnetAgent: true?
Please enter a value for RegisteredAgentFirstName when isCorpnetAgent: true?Setting registeredAgentIsCorpnetAgent: true does not auto-populate the address fields. Populate the full RA address block with CorpNet's RA service address: 2710 Gateway Oaks Drive, Suite 150N, Sacramento, CA 95833 (US).
Why does GET return null for fields the spec marks required?
CorpNet's backend uses Salesforce, where child relationships (contact, businessAddress, companyInfo) are linked via async triggers after the parent order commits. There's a brief window — seconds to minutes — where GET may return null on these fields. Workflow-phase-dependent fields (orderFilingType, filedDate, formedEntityId) stay null until the order phase advances past Order Received. Retry after ~30 seconds for a complete read.
Tax Registration gotchas
Why does GET return less data than POST?
GET returns a status summary only — id, orderGuid, orderPhase, orderStatus, accountNumbers, taxRates, agencyAccounts. Submitted business details, state info, and responsible parties are not retrievable through the API. Retain a local copy of the submission at creation time if you need to re-display them.
Why does GET on a non-existent order return HTTP 400?
Known API quirk: the API returns 400 (rather than 404) for not-found, with body {"statusCode": 200, "message": "success", "data": {"partnerOrder": null}}. Detect not-found defensively by checking data.partnerOrder === null rather than trusting the status fields.
Operations
How do I get a key?
Contact your CorpNet account manager. Tokens are issued at partner onboarding. Staging and production tokens are distinct.
Do you support webhooks?
Not currently. Order-status updates require polling Get Full Order Details. Webhook support is on the roadmap; contact your account manager for status.