Connection Lifecycle

What Is a Connection?

A connection in graphiteConnect describes the relationship between two entities in the Graphite network. Fully connected entities can exchange profile data and receive notifications when relevant data changes.

Connections can be initiated by anyone in the network — both to entities already in graphiteConnect and to companies that have not yet joined.

Connection Phases

Connections move through defined phases from initial invite to full connection (or disconnection). The connectionPhases query parameter on GET /changes/connections lets you filter the changes list by phase.

Phase	Description
`invite`	Invitation has been created but not yet sent to the recipient
`accept`	Invitation has been sent and is awaiting acceptance by the recipient
`collaborate`	Entities can see some of each other's data and are working toward a full connection
`connect`	Collaboration tasks are complete and the connection is awaiting final approvals
`connected`	The connection is fully established
`disconnect`	The connection is in the process of being disconnected
`disconnected`	The connection is disconnected; it can be reconnected if needed

ERP Recommendation: For most ERP integrations, filter connectionPhases to connected,disconnected to process only fully established or recently ended relationships.

Invite Process

When a user initiates an invite, graphiteConnect creates a connection between the two entities. The invite phase allows the inviting entity to complete any internal processes or approvals before the invite is actually sent. Until the invite is sent, it is invisible to the recipient.

Existing graphiteConnect entity: The recipient will receive a task and a notification.
Company not yet in graphiteConnect: graphiteConnect creates a placeholder entity and sends an email to the invited contact.

Duplicate Entity Detection

graphiteConnect makes every effort to avoid duplicate entities in the network. Matching checks occur at two points:

During invite: If the invited user is already part of graphiteConnect and has associations with one or more entities, graphiteConnect identifies the match.
During profile completion: When the invited user is filling out tax information and company name, graphiteConnect searches its network for likely matching entities.

Redirected Invites

If an invited user decides to redirect their connection to an existing graphiteConnect entity (rather than completing a new profile), graphiteConnect handles the redirect as follows:

If the originally invited entity was a placeholder, the placeholder entity is deleted.
If the existing entity already has a connection with the inviting entity, the duplicate connection is deleted. Deleted connections appear in the deleted section of the connection/changes API.
If the existing entity and the inviting entity have no prior connection, the respondingEntity field of the placeholder connection is updated to point to the existing entity.

Disconnecting

The behavior on disconnect depends on the phase at which the disconnection occurs:

Before the connected phase: graphiteConnect will delete the connection outright.
At or after the connected phase: The connection moves through the disconnect phase and then into the disconnected phase. Disconnected connections can be reconnected.

Connection Changes API

Use GET /changes/connections to monitor connection lifecycle changes. The connectionPhases parameter filters which phases are included in the response. The deleted section of the response includes recently deleted connections.