# PartnerSharedIngressService

Partners can authorize as either identity type.

```http
Authorization: Bearer <token>
x-identity-uuid: <uuid>
x-identity-type: COMPANY | EMPLOYEE
```

## ListAgreements

Returns a status for overall agreements, and a list of agreements to sign. Agreements may take up to 30 seconds to generate. This will be kicked off asynchronously as soon as upstream dependencies are complete, and documents may be available by the time this endpoint is called; however, we recommend that partners check the status on the returned object to ensure that agreements are ready.

```protobuf
service PartnerSharedIngressService {
  rpc ListAgreements(ListAgreementsRequest) returns (ListAgreementsResponse);
}

message ListAgreementsRequest {
  repeated Agreement.Status statuses = 1;
  repeated Agreement.Type types = 2;
}

message ListAgreementsResponse {
  repeated Agreement agreements = 1;
}
```

**Data types:** [Agreement](/core-data-types/identity-and-agreements#agreement)

**REST:** [`POST /v1/partner-rpc/com.basiccapital.systems.ingress.partner.PartnerSharedIngressService/ListAgreements`](/openapi/partnersharedingressservice/listagreements)

## MarkAgreementsSigned

```protobuf
service PartnerSharedIngressService {
  rpc MarkAgreementsSigned(MarkAgreementsSignedRequest) returns (MarkAgreementsSignedResponse);
}

message MarkAgreementsSignedRequest {
  message SignedAgreements {
    string agreement_uuid = 1;
    ConsentInfo consent_info = 2;
  }

  repeated SignedAgreements agreements = 1;
}

message MarkAgreementsSignedResponse {}
```

**Data types:** [ConsentInfo](/core-data-types/identity-and-agreements#consentinfo)

**REST:** [`POST /v1/partner-rpc/com.basiccapital.systems.ingress.partner.PartnerSharedIngressService/MarkAgreementsSigned`](/openapi/partnersharedingressservice/markagreementssigned)

## GetOrCreateUser

Partners should call this endpoint to create a user in Basic Capital and fetch an invite token for SSO. Authorize as either the company or the employee, depending on whether they want to log into the employer dashboard or member app.

Note that if a single user has an admin and employee account, they will receive *separate invite tokens* for each entity type; however, when they accept the invite via SSO, their user in Basic Capital will have access to both accounts. This flow will be invisible to the user, but is an important distinction for partners if they plan to cache the user status. We recommend simply calling `GetOrCreateUser` each time to avoid confusion.

```protobuf
service PartnerSharedIngressService {
  rpc GetOrCreateUser(GetOrCreateUserRequest) returns (GetOrCreateUserResponse);
}

message GetOrCreateUserRequest {
  UserInviteInfo invite_info = 1;
}

message GetOrCreateUserResponse {
  BasicCapitalUserStatus user_status = 1;
  optional string accept_invite_token = 2;
}
```

**Data types:** [BasicCapitalUserStatus](/core-data-types/identity-and-agreements#basiccapitaluserstatus), [UserInviteInfo](/core-data-types/identity-and-agreements#userinviteinfo)

**REST:** [`POST /v1/partner-rpc/com.basiccapital.systems.ingress.partner.PartnerSharedIngressService/GetOrCreateUser`](/openapi/partnersharedingressservice/getorcreateuser)

## BeginIdentityVerification

Opens a verification session. The returned `verification_uuid` identifies the session; `auth_token` is the provider session token to hand to the provider's client SDK, where the provider requires one.

Employees and trustees must pass identity verification as a first step before any interactions with the platform. Verification runs in two calls: begin opens a session with the verification provider, then complete it with the token that provider returns to your client.

If the person already has a Basic Capital account under the same SSN, verification cannot complete. `PartnerEmployeeIngressService.GetEmployeeOnboardingStatus` will return a `kyc_status` of `MUST_LINK_ACCOUNT`, and the employee must link their existing account before continuing. See the [Single Sign-On Guide](#single-sign-on-guide) below for more information.

By default, Basic Capital uses [Footprint](https://onefootprint.com/) as an IdV provider, which partners can embed in their onboarding experience; however, if partners run KYC and are able to provide the required data fields, we can work to integrate with you as a provider.

```protobuf
service PartnerSharedIngressService {
  rpc BeginIdentityVerification(BeginIdentityVerificationRequest) returns (BeginIdentityVerificationResponse);
}

message BeginIdentityVerificationRequest {
  VerificationProvider verification_provider = 1;
  VerificationType verification_type = 2;
}

message BeginIdentityVerificationResponse {
  string verification_uuid = 1;
  optional string auth_token = 2;
}
```

**Data types:** [VerificationProvider](/core-data-types/identity-and-agreements#verificationprovider), [VerificationType](/core-data-types/identity-and-agreements#verificationtype)

**REST:** [`POST /v1/partner-rpc/com.basiccapital.systems.ingress.partner.PartnerSharedIngressService/BeginIdentityVerification`](/openapi/partnersharedingressservice/beginidentityverification)

## CompleteIdentityVerification

Completes the session opened above, using the `verification_uuid` returned by `BeginIdentityVerification` and the `verification_token` your client receives from the provider on success.

A `VERIFICATION_STATUS_PENDING` result means the provider has not returned a decision yet; poll `GetEmployeeOnboardingStatus` for the resulting `kyc_status` rather than re-running verification.

```protobuf
service PartnerSharedIngressService {
  rpc CompleteIdentityVerification(CompleteIdentityVerificationRequest) returns (CompleteIdentityVerificationResponse);
}

message CompleteIdentityVerificationRequest {
  string verification_uuid = 1;
  string verification_token = 2;
}

message CompleteIdentityVerificationResponse {
  VerificationStatus verification_status = 2;
}
```

**Data types:** [VerificationStatus](/core-data-types/identity-and-agreements#verificationstatus)

**REST:** [`POST /v1/partner-rpc/com.basiccapital.systems.ingress.partner.PartnerSharedIngressService/CompleteIdentityVerification`](/openapi/partnersharedingressservice/completeidentityverification)